Mercurial > kallithea
view docs/installation_win.rst @ 6532:33b71a130b16
templates: properly escape inline JavaScript values
TLDR: Kallithea has issues with escaping values for use in inline JS.
Despite judicious poking of the code, no actual security vulnerabilities
have been found, just lots of corner-case bugs. This patch fixes those,
and hardens the code against actual security issues.
The long version:
To embed a Python value (typically a 'unicode' plain-text value) in a
larger file, it must be escaped in a context specific manner. Example:
>>> s = u'<script>alert("It\'s a trap!");</script>'
1) Escaped for insertion into HTML element context
>>> print cgi.escape(s)
<script>alert("It's a trap!");</script>
2) Escaped for insertion into HTML element or attribute context
>>> print h.escape(s)
<script>alert("It's a trap!");</script>
This is the default Mako escaping, as usually used by Kallithea.
3) Encoded as JSON
>>> print json.dumps(s)
"<script>alert(\"It's a trap!\");</script>"
4) Escaped for insertion into a JavaScript file
>>> print '(' + json.dumps(s) + ')'
("<script>alert(\"It's a trap!\");</script>")
The parentheses are not actually required for strings, but may be needed
to avoid syntax errors if the value is a number or dict (object).
5) Escaped for insertion into a HTML inline <script> element
>>> print h.js(s)
("\x3cscript\x3ealert(\"It's a trap!\");\x3c/script\x3e")
Here, we need to combine JS and HTML escaping, further complicated by
the fact that "<script>" tag contents can either be parsed in XHTML mode
(in which case '<', '>' and '&' must additionally be XML escaped) or
HTML mode (in which case '</script>' must be escaped, but not using HTML
escaping, which is not available in HTML "<script>" tags). Therefore,
the XML special characters (which can only occur in string literals) are
escaped using JavaScript string literal escape sequences.
(This, incidentally, is why modern web security best practices ban all
use of inline JavaScript...)
Unsurprisingly, Kallithea does not do (5) correctly. In most cases,
Kallithea might slap a pair of single quotes around the HTML escaped
Python value. A typical benign example:
$('#child_link').html('${_('No revisions')}');
This works in English, but if a localized version of the string contains
an apostrophe, the result will be broken JavaScript. In the more severe
cases, where the text is user controllable, it leaves the door open to
injections. In this example, the script inserts the string as HTML, so
Mako's implicit HTML escaping makes sense; but in many other cases, HTML
escaping is actually an error, because the value is not used by the
script in an HTML context.
The good news is that the HTML escaping thwarts attempts at XSS, since
it's impossible to inject syntactically valid JavaScript of any useful
complexity. It does allow JavaScript errors and gibberish to appear on
the page, though.
In these cases, the escaping has been fixed to use either the new 'h.js'
helper, which does JavaScript escaping (but not HTML escaping), OR the
new 'h.jshtml' helper (which does both), in those cases where it was
unclear if the value might be used (by the script) in an HTML context.
Some of these can probably be "relaxed" from h.jshtml to h.js later, but
for now, using h.jshtml fixes escaping and doesn't introduce new errors.
In a few places, Kallithea JSON encodes values in the controller, then
inserts the JSON (without any further escaping) into <script> tags. This
is also wrong, and carries actual risk of XSS vulnerabilities. However,
in all cases, security vulnerabilities were narrowly avoided due to other
filtering in Kallithea. (E.g. many special characters are banned from
appearing in usernames.) In these cases, the escaping has been fixed
and moved to the template, making it immediately visible that proper
escaping has been performed.
Mini-FAQ (frequently anticipated questions):
Q: Why do everything in one big, hard to review patch?
Q: Why add escaping in specific case FOO, it doesn't seem needed?
Because the goal here is to have "escape everywhere" as the default
policy, rather than identifying individual bugs and fixing them one
by one by adding escaping where needed. As such, this patch surely
introduces a lot of needless escaping. This is no different from
how Mako/Pylons HTML escape everything by default, even when not
needed: it's errs on the side of needless work, to prevent erring
on the side of skipping required (and security critical) work.
As for reviewability, the most important thing to notice is not where
escaping has been introduced, but any places where it might have been
missed (or where h.jshtml is needed, but h.js is used).
Q: The added escaping is kinda verbose/ugly.
That is not a question, but yes, I agree. Hopefully it'll encourage us
to move away from inline JavaScript altogether. That's a significantly
larger job, though; with luck this patch will keep us safe and secure
until such a time as we can implement the real fix.
Q: Why not use Mako filter syntax ("${val|h.js}")?
Because of long-standing Mako bug #140, preventing use of 'h' in
filters.
Q: Why not work around bug #140, or even use straight "${val|js}"?
Because Mako still applies the default h.escape filter before the
explicitly specified filters.
Q: Where do we go from here?
Longer term, we should stop doing variable expansions in script blocks,
and instead pass data to JS via e.g. data attributes, or asynchronously
using AJAX calls. Once we've done that, we can remove inline JavaScript
altogether in favor of separate script files, and set a strict Content
Security Policy explicitly blocking inline scripting, and thus also the
most common kind of cross-site scripting attack.
| author | Søren Løvborg <sorenl@unity3d.com> |
|---|---|
| date | Tue, 28 Feb 2017 17:19:00 +0100 |
| parents | d9e6e489f171 |
| children | 2c3d30095d5e |
line wrap: on
line source
.. _installation_win: ==================================================== Installation on Windows (7/Server 2008 R2 and newer) ==================================================== First time install ------------------ Target OS: Windows 7 and newer or Windows Server 2008 R2 and newer Tested on Windows 8.1, Windows Server 2008 R2 and Windows Server 2012 To install on an older version of Windows, see `<installation_win_old.html>`_ Step 1 -- Install Python ^^^^^^^^^^^^^^^^^^^^^^^^ Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side. .. warning:: Python 3.x is not supported. - Download Python 2.x.y from http://www.python.org/download/ - Choose and click on the version - Click on "Windows X86-64 Installer" for x64 or "Windows x86 MSI installer" for Win32. - Disable UAC or run the installer with admin privileges. If you chose to disable UAC, do not forget to reboot afterwards. While writing this guide, the latest version was v2.7.9. Remember the specific major and minor versions installed, because they will be needed in the next step. In this case, it is "2.7". Step 2 -- Python BIN ^^^^^^^^^^^^^^^^^^^^ Add Python BIN folder to the path. This can be done manually (editing "PATH" environment variable) or by using Windows Support Tools that come pre-installed in Windows Vista/7 and later. Open a CMD and type:: SETX PATH "%PATH%;[your-python-path]" /M Please substitute [your-python-path] with your Python installation path. Typically this is ``C:\\Python27``. Step 3 -- Install pywin32 extensions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Download pywin32 from: http://sourceforge.net/projects/pywin32/files/ - Click on "pywin32" folder - Click on the first folder (in this case, Build 219, maybe newer when you try) - Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe" for Win32) where x is the minor version of Python you installed. When writing this guide, the file was: http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win-amd64-py2.7.exe/download (x64) http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download (Win32) Step 4 -- Install pip ^^^^^^^^^^^^^^^^^^^^^ pip is a package management system for Python. You will need it to install Kallithea and its dependencies. If you installed Python 2.7.9+, you already have it (as long as you ran the installer with admin privileges or disabled UAC). If it was not installed or if you are using Python>=2.6,<2.7.9: - Go to https://bootstrap.pypa.io - Right-click on get-pip.py and choose Saves as... - Run "python2 get-pip.py" in the folder where you downloaded get-pip.py (may require admin access). .. note:: See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows for details and alternative methods. Note that pip.exe will be placed inside your Python installation's Scripts folder, which is likely not on your path. To correct this, open a CMD and type:: SETX PATH "%PATH%;[your-python-path]\Scripts" /M Step 5 -- Kallithea folder structure ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Create a Kallithea folder structure. This is only an example to install Kallithea. Of course, you can change it. However, this guide will follow the proposed structure, so please later adapt the paths if you change them. Folders without spaces are recommended. Create the following folder structure:: C:\Kallithea C:\Kallithea\Bin C:\Kallithea\Env C:\Kallithea\Repos Step 6 -- Install virtualenv ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea. It is strongly recommended to use it to ensure that Kallithea does not change a dependency that other software uses or vice versa. In a command prompt type:: pip install virtualenv Virtualenv will now be inside your Python Scripts path (C:\\Python27\\Scripts or similar). To create a virtual environment, run:: virtualenv C:\Kallithea\Env Step 7 -- Install Kallithea ^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies. Some Python packages use managed code and need to be compiled. This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7. Download and install "Microsoft Visual C++ Compiler for Python 2.7" from http://aka.ms/vcpython27 .. note:: You can also install the dependencies using already compiled Windows binaries packages. A good source of compiled Python packages is http://www.lfd.uci.edu/~gohlke/pythonlibs/. However, not all of the necessary packages for Kallithea are on this site and some are hard to find, so we will stick with using the compiler. In a command prompt type (adapting paths if necessary):: cd C:\Kallithea\Env\Scripts activate pip install --upgrade pip setuptools The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar (depending of your folder structure). Then type:: pip install kallithea .. note:: This will take some time. Please wait patiently until it is fully complete. Some warnings will appear. Don't worry, they are normal. Step 8 -- Install Git (optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Mercurial being a python package, was installed automatically when doing ``pip install kallithea``. You need to install Git manually if you want Kallithea to be able to host Git repositories. See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions. The location of the Git binaries (like ``c:\path\to\git\bin``) must be added to the ``PATH`` environment variable so ``git.exe`` and other tools like ``gzip.exe`` are available. Step 9 -- Configuring Kallithea ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Steps taken from `<setup.html>`_ You have to use the same command prompt as in Step 7, so if you closed it, reopen it following the same commands (including the "activate" one). When ready, type:: cd C:\Kallithea\Bin paster make-config Kallithea production.ini Then you must edit production.ini to fit your needs (IP address, IP port, mail settings, database, etc.). `NotePad++`__ or a similar text editor is recommended to properly handle the newline character differences between Unix and Windows. __ http://notepad-plus-plus.org/ For the sake of simplicity, run it with the default settings. After your edits (if any) in the previous command prompt, type:: paster setup-db production.ini .. warning:: This time a *new* database will be installed. You must follow a different process to later :ref:`upgrade <upgrade>` to a newer Kallithea version. The script will ask you for confirmation about creating a new database, answer yes (y) The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar). The script will ask you for the admin username and password, answer "admin" + "123456" (or whatever you want) The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want). If you make a mistake and the script doesn't end, don't worry: start it again. If you decided not to install Git, you will get errors about it that you can ignore. Step 10 -- Running Kallithea ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type:: paster serve production.ini Open your web server, and go to http://127.0.0.1:5000 It works!! :-) Remark: If it does not work the first time, Ctrl-C the CMD process and start it again. Don't forget the "http://" in Internet Explorer. What this guide does not cover: - Installing Celery - Running Kallithea as a Windows Service. You can investigate here: - http://pypi.python.org/pypi/wsgisvc - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/ - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service - Using Apache. You can investigate here: - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4