diff --git a/ICAL.txt b/ICLA.txt old mode 100755 new mode 100644 similarity index 100% rename from ICAL.txt rename to ICLA.txt diff --git a/SUMMARY.md b/SUMMARY.md index 89c744c..00a7fa7 100755 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,7 +2,7 @@ * [Introduction]({%}?page=README) ## Setup -* [Install]({%}?page=setup/install) +* [Installation]({%}?page=setup/install) * [First Steps]({%}?page=setup/first_steps) ## Administration @@ -23,6 +23,7 @@ ## User Interface (UI) +* [General]({%}?page=ui/general) * [Hotkeys]({%}?page=ui/hotkeys) -* [Tables]({%}?page=ui/tables) -* [Search]({%}?page=ui/search) + diff --git a/maintenance/monitoring.md b/maintenance/monitoring.md index 4caa7a1..7d88082 100755 --- a/maintenance/monitoring.md +++ b/maintenance/monitoring.md @@ -8,6 +8,8 @@ The application provides activity monitoring through error logging as well as au The error logging creates log entries whenever an error occurs. These error logs contain specific information about what, when, where and who caused the error. These error messages indicate that something is not working as intended and require immediate attention. These errors however are not known to the development team since they are application specific; in order to inform the development team that there is an error it's possible to forward this error via a simple click of a button. This error can now get inspected and fixed. Make sure to report all errors so that they can get fixed. Errors that appear because of changes in the source code will be ignored since customer or third party code changes are not supported or allowed. +> Logs are stored in `Logs/` + ### Audit Trails The audit trails are used by modules in order to log user and system activities such as changes/updates to existing elements or the creation and deletion of elements. Elements in this context refers to all database data and state changes. These logs are important in order to investigate changes by certain people or to certain elements. Activity logs can be an important factor for audits as they prove that all changes can be inspected, supervised and tracked back. These log files can be used for compliance reports as well as approval reports where certain activities need to be approved. While there are modules like the `Workflow` module which allow pre-approval in some cases a post-approval may be necessary and in these situations these logs can be used to generate a report which then can be approved. @@ -15,3 +17,9 @@ The audit trails are used by modules in order to log user and system activities ## External Despite the internal monitoring features additional third party monitoring is recommended. Please make yourself familiar with tools that monitor network activities and server activities. These tools help to provide a high availability of your server and application, help with monitoring suspicious behavior and find and solve problems in a timely manner. In addition third party monitoring tools can help to optimize server and application configurations. + +## Debugging + +If you need to perform additional inspections and logs due to some issues you can temporarily enable a debugging mode by adding `&debug` or `?debug` at the end of the url. + +This debug mode is only available for users that have full writing permissions for a specific unit and application (aka admin permissions). diff --git a/security/application.md b/security/application.md index c0761bc..aecc0f4 100755 --- a/security/application.md +++ b/security/application.md @@ -31,3 +31,21 @@ Updates are very important not only to implement the newest features but also to ## Modules, Extensions, Themes etc. Only download software components from the official website never trust any third party services. All software components on the official website get tested and reviewed internally in order to ensure no malicious behavior. + +## Which security features does the application implement? + +* We use Cross-Site Request Forgery tokens (`CSRF`) for API calls to prevent malicious executions through hidden third-party calls +* We use a strict Content Security Policy (`CSP`) and `nonces` to prevent malicious code infiltration such as Cross-Site Scripting (`XSS`) +* We use BCRYPT/Blowfish hashing with a randomly generated salt for user passwords +* Some selected sensitive data is encrypted in the database and on the file system using the encryption library `libsodium` +* We use backend validation on top of frontend validation +* We almost never sanitize data, data is either valid or gets dismissed +* We extensively test our source code +* We escape user generated text data +* Audit logs tracking changes in the database are first class citizens and are part of every installation by default +* In addition to database audit logs we also generate error logs +* Database query parameters are either simple datatypes (int, bool, float), use quotation for strings or use prepared statements +* File paths are guarded to be within the application path +* We mostly use soft deletes making it possible to restore most of the database data unless overwritten +* We provide extensive user and group permission handling +* Our default server configuration prevents the direct execution of any scripts aside from the main application \ No newline at end of file diff --git a/security/mentality.md b/security/mentality.md index e10675e..17388cf 100755 --- a/security/mentality.md +++ b/security/mentality.md @@ -1,6 +1,6 @@ # Security Mentality -Security layers and guidelines are usually seen by the every-day-user as necessary evil. However without a good mindset no amount of guidelines or even technical security measurements will protect the integrity of the server and data. The thought process often goes along these lines: +Security layers and guidelines are usually seen by the every-day-user as necessary evil. However, without a good mindset no amount of guidelines or even technical security measurements will protect the integrity of the server and data. The thought process often goes along these lines: 1. I will not get attacked! 2. I don't have any data that need protection! diff --git a/setup/first_steps.md b/setup/first_steps.md index 6f5f255..78048b3 100755 --- a/setup/first_steps.md +++ b/setup/first_steps.md @@ -57,7 +57,7 @@ These restrictions show that it is possible to do very fine/granular permissions ## Accounts -By default only admin users can create new accounts. However it is possible to allow users to register by themselves in the admin module settings. Self-registered users are always part of the `user` group. Make sure the `user` group permissions are designed while keeping that in mind. +By default only admin users can create new accounts. However, it is possible to allow users to register by themselves in the admin module settings. Self-registered users are always part of the `user` group. Make sure the `user` group permissions are designed while keeping that in mind. If a admin user creates a new account you must decide if the user/account should also be allowed to login/have a profile or if this account is just an internal account. diff --git a/setup/install.md b/setup/install.md index 494bfe0..7c86835 100755 --- a/setup/install.md +++ b/setup/install.md @@ -1,6 +1,6 @@ # Installation -The easiest and most common way to install the application is through the web installer located at https://127.0.0.1/Install if you put it into your apache2 directory. Alternatively you can also install it through a command line interface (cli). +The easiest and most common way to install the application is through the web installer located at [https://127.0.0.1/Install](https://127.0.0.1/Install) if you put it into your apache2 directory. Alternatively you can also install it through a command line interface (cli). * [Server Recommendations]({%}#server-recommendations) * [Webserver and Database]({%}#web-server-and-database) @@ -41,11 +41,13 @@ sudo apt-get install software-properties-common apache2 mariadb-server mariadb-c sudo a2enmod rewrite sudo a2enmod headers + +sudo service apache2 restart ``` ## Php -The minimum php version requirement in the following installation guide is version 8.0. +The minimum php version requirement in the following installation guide is version 8.2. ### Windows @@ -56,7 +58,9 @@ On Windows php should already be installed with the web servers mentioned above The following extensions are recommended and sometimes even mandatory: ```sh -sudo apt-get install php8.1 php8.1-dev php8.1-cli php8.1-common php8.1-mysql php8.1-pgsql php8.1-xdebug php8.1-opcache php8.1-pdo php8.1-sqlite php8.1-mbstring php8.1-curl php8.1-imap php8.1-bcmath php8.1-zip php8.1-dom php8.1-xml php8.1-phar php8.1-gd php-pear sqlite3 +sudo apt-get install php8.2 php8.2-dev php8.2-cli php8.2-common php8.2-mysql php8.2-pgsql php8.2-xdebug php8.2-opcache php8.2-pdo php8.2-sqlite php8.2-mbstring php8.2-curl php8.2-imap php8.2-bcmath php8.2-zip php8.2-dom php8.2-xml php8.2-phar php8.2-gd php-pear sqlite3 + +sudo service apache2 restart ``` ## Software @@ -134,6 +138,7 @@ sudo apt-get install imagemagick Before you can install the application you need to put the application files into the web server directory. This directory depends on the web server which you used and the web server configuration. + #### Windows By default the windows directory should be `C:/xampp/htdocs`. Remove all files in this directory and put all the files of the Karaka application into this directory. @@ -142,9 +147,20 @@ By default the windows directory should be `C:/xampp/htdocs`. Remove all files i By default the linux directory should be `/var/www/htm`. Remove all files in this directory and put all the files of the Karaka application into this directory. +#### File permissions + +File permissions should only be an issue on linux. You can change the file permissions of directories as follows: + +```sh +sudo chown -R www-data:www-data . +sudo find . -type d -exec chmod 755 {} \; +sudo find . -type f -exec chmod 644 {} \; +sudo chmod 640 config.php +``` + ### Web Installer -If you installed the application on your local computer you can open a browser window and navigate to [http://127.0.0.1/Install](http://127.0.0.1/Install). If you installed it on a remote server navigate to the URL of that server. +If you installed the application on your local computer you can open a browser window and navigate to [http://127.0.0.1/Install](http://127.0.0.1/Install). If you installed it on a remote server, navigate to the URL of that server. Click yourself through the installation and fill out the forms during the installation process. @@ -152,14 +168,6 @@ Click yourself through the installation and fill out the forms during the instal On the page called pre-installation check the installation script will check and inform you if the necessary php extensions and file permissions are available. Only requirements marked as optional can be missing. If any other requirements fail please don't continue with the installation and fix these requirements first. Once you fixed the requirements reload the installation script! -##### File permissions - -File permissions should only be an issue on linux. You can change the file permissions of directories as follows: - -```sh -sudo chmod -R 755 /var/www/htm/Modules -``` - ##### Php extensions If the extension is already installed you can just add it to your `php.ini` file of extension loading files in `conf.d/`. e.g.: @@ -169,14 +177,14 @@ extension=mbstring.dll // Example in case you are installing on Windows extension=mbstring.so // Example in case you are installing on Linux ``` -> The `php.ini` file can be **often** found at C:/xampp/php/php.ini on Windows and /etc/php/8.0/apache2/php.ini on Linux. +> The `php.ini` file can be **often** found at C:/xampp/php/php.ini on Windows and /etc/php/X.X/apache2/php.ini on Linux. > > Sometimes the ending .dll and .so must be omitted depending on the version and configuration of your php installation. If the extension is not installed and not activated you can alternatively run the following commands on Linux (just as example): ```sh -sudo apt-get install php8.1-mbstring +sudo apt-get install php8.2-mbstring sudo phpenmod mbstring ``` @@ -224,7 +232,7 @@ Here you must define the admin login name, the admin password and email. ##### Top Level domain -The top level domain is the domain name where you installed the application. If you only installed it locally, it is 127.0.0.1. If you installed it on your web server, then you input the domain name e.g. `karaka.app` +The top level domain is the domain name where you installed the application. If you only installed it locally, it is 127.0.0.1. If you installed it on your web server, then you input the domain name e.g. `jingga.app` ##### Web Subdirectory @@ -233,3 +241,11 @@ The web subdirectory by default is `/`. If you installed the application in a su #### Install After clicking install you will either receive a message that something went wrong e.g. some configurations are wrong (please fix them) or the installation will redirect you to the login if everything went smoothly. Please make sure to delete the `Install` directory so that no-one else can use it. + +### Cli Installer + +Navigate to the `Install` directory, modify the cli.php and config.php and then run the cli.php as www-data + +```sh +sudo -u www-data php cli.php +``` \ No newline at end of file diff --git a/ui/general.md b/ui/general.md new file mode 100644 index 0000000..372038d --- /dev/null +++ b/ui/general.md @@ -0,0 +1,7 @@ +# General UI + +## Dark mode + +Some users prefer to use the darkmode of a website. Unfortunately due to the way Windows settings work it is no longer feasible to automatically provide the dark mode based on these settings. However, you may enable dark mode by adding `&darkmode` or `?darkmode` at the end of the url. + +> Dark mode is only experimental and we recommend useres to use the default theme \ No newline at end of file diff --git a/ui/hotkeys.md b/ui/hotkeys.md index 1819641..82357f5 100755 --- a/ui/hotkeys.md +++ b/ui/hotkeys.md @@ -10,6 +10,8 @@ The following hotkeys allow you to navigate the application. | Global | Ctrl + Right Arrow | Jump to next UI element | | Global | Ctrl + Left Arrow | Jump to previous UI element | | Global | Ctrl + B | Go to previous page (back) | +| Global | Alt + Right Arrow | Go to previous page (back) | +| Global | Alt + Left Arrow | Go to nex page (only works after going back) | | Link or Tab | Enter | Activate/execute/follow link | ## Form Interaction @@ -27,4 +29,4 @@ The following hotkeys provide table interactions. | Element | Hotkey | Action | | ----------------- | ------------------ | --------------------------------------------------- | | Table | Ctrl + A | Select all table elements | -| Table | Ctrl + E | Export selected elements to excel | +| Table | Ctrl + E | Export selected elements to excel (*coming soon*) |