From 32a2de0c3ff6dec5bc3ef6496b7e3cdde671e5f3 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Thu, 27 Oct 2022 14:06:53 +0200 Subject: [proxy] document policy selection --- src/hydrilla/locales/en_US/LC_MESSAGES/messages.po | 128 +++++++++++++++++++-- .../info_pages_templates/info_base.html.jinja | 9 +- .../info_pages_templates/js_rule_info.html.jinja | 4 +- .../info_pages_templates/payload_info.html.jinja | 4 +- src/hydrilla/proxy/self_doc.py | 2 +- src/hydrilla/proxy/self_doc/doc_base.html.jinja | 16 ++- .../proxy/self_doc/policy_selection.html.jinja | 87 ++++++++++++++ 7 files changed, 234 insertions(+), 16 deletions(-) create mode 100644 src/hydrilla/proxy/self_doc/policy_selection.html.jinja diff --git a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po index 2b922ed..c6426fa 100644 --- a/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po +++ b/src/hydrilla/locales/en_US/LC_MESSAGES/messages.po @@ -14,7 +14,7 @@ msgid "" msgstr "" "Project-Id-Version: hydrilla 2.0\n" "Report-Msgid-Bugs-To: koszko@koszko.org\n" -"POT-Creation-Date: 2022-10-26 16:03+0200\n" +"POT-Creation-Date: 2022-10-27 14:02+0200\n" "PO-Revision-Date: 2022-02-12 00:00+0000\n" "Last-Translator: Wojtek Kosior \n" "Language: en_US\n" @@ -220,39 +220,39 @@ msgstr "" "\n" "{}" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:34 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:39 msgid "info.base.title" msgstr "Page info" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:39 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:44 msgid "info.base.heading.page_info" msgstr "Haketilo page handling details" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:42 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:47 msgid "info.base.page_url_label" msgstr "Page URL" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:50 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:55 msgid "info.base.page_policy_label" msgstr "Active policy" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:62 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:69 msgid "info.base.more_config_options_label" msgstr "Configure" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:70 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:77 msgid "info.base.this_site_script_blocking_button" msgstr "JS blocking on this site" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:73 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:80 msgid "info.base.this_site_payload_button" msgstr "Payload for this site" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:76 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:83 msgid "info.base.this_page_script_blocking_button" msgstr "JS blocking on this page" -#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:79 +#: src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja:86 msgid "info.base.this_page_payload_button" msgstr "Payload for this page" @@ -319,6 +319,114 @@ msgstr "Requested file could not be found." msgid "api.resource_not_enabled_for_access" msgstr "Requested resource is not enabled for access." +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:24 +msgid "doc.policy_selection.title" +msgstr "Policy selection" + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:27 +msgid "doc.policy_selection.h_big" +msgstr "Page policy selection" + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:31 +msgid "doc.policy_selection.intro" +msgstr "When a web page is opened, Haketilo is capable of either" + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:34 +msgid "doc.policy_selection.enabled_payload_case" +msgstr "blocking page's own scripts and injecting payload configured by the user," + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:37 +msgid "doc.policy_selection.auto_payload_case" +msgstr "" +"blocking page's own scripts and injecting an automatically-chosen payload" +" that is usable with the page," + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:40 +msgid "doc.policy_selection.ask_payload_case" +msgstr "" +"presenting a dialog asking whether to enable an automatically-chosen " +"payload that is usable with the page," + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:43 +msgid "doc.policy_selection.block_js_case" +msgstr "blocking page's own scripts or" + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:46 +msgid "doc.policy_selection.allow_js_case" +msgstr "" +"allowing page's own scripts to execute normally (i.e. not modifying the " +"page in any meaningful way)." + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:53 +msgid "doc.policy_selection.h_medium.precedence" +msgstr "Policy precedence" + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:56 +msgid "doc.policy_selection.html.precedence_general_{patterns_link}" +msgstr "" +"User configures Haketilo's behavior by defining script-blocking and " +"-allowing rules and by adding and enabling packages. Each rule and each " +"package payload has a {patterns_link}. This pattern determined which " +"pages the policy is compatible with. Patterns also have well-defined " +"specificity. When multiple rules and packages are combatible with given " +"page's URL, the one with the most specific pattern \"wins\". In case of a" +" tie, payload injection is assumed to take precedence over rule " +"application." + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:57 +msgid "doc.policy_selection.precedence_general.patterns_link_text" +msgstr "URL pattern" + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:63 +msgid "doc.policy_selection.html.precedence_nonenabled_{settings_link}" +msgstr "" +"In the absence of suitable rules and enabled packages, Haketilo may " +"consider non-enabled packages that are suitable for use on the currently-" +"visited site. It will either inject package payload automatically, ask " +"the user whether to enable the package or ignore it completely. The user " +"can switch between these 3 behaviors on the Haketilo {settings_link}. " +"Packages that were explicitly marked as disabled will always be ignored. " +"Pattern specificity is also taken into account in case of multiple " +"packages." + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:64 +msgid "doc.policy_selection.precedence_nonenabled.settings_link_text" +msgstr "settings page" + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:70 +msgid "doc.policy_selection.html.precedence_fallback_{settings_link}" +msgstr "" +"When absolutely no explicit policy appears suitable for given page, " +"Haketilo will apply its default script handling behavrior. Whether " +"JavaScript is blocked or allowed by default is also determined by user's " +"choice on the {settings_link}." + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:71 +msgid "doc.policy_selection.precedence_fallback.settings_link_text" +msgstr "settings page" + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:78 +msgid "doc.policy_selection.special_cases.h_medium" +msgstr "Special cases" + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:81 +msgid "doc.policy_selection.special_cases.html.exepmt_and_error" +msgstr "" +"The sites served by Haketilo itself are exempt from all policies. These " +"are http://hkt.mitm.it, https://hkt.mitm.it and" +" http://mitm.it. Additionally, if Haketilo experiences an " +"internal error (e.g. because it could not parse current URL as sent in by" +" the browser), it will try to block page's JavaScript as a security " +"measure." + +#: src/hydrilla/proxy/self_doc/policy_selection.html.jinja:85 +msgid "doc.policy_selection.special_cases.internal_policies" +msgstr "" +"Internally, Haketilo also has a special high-priority policy for serving " +"files used by payloads and for making its APIs accessible to payload " +"scripts. This is, however, an implementation detail and casual users need" +" not care about it nor understand these nuances." + #: src/hydrilla/proxy/self_doc/url_patterns.html.jinja:23 msgid "doc.url_patterns.title" msgstr "URL patterns" diff --git a/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja index 0785039..ccdc7c8 100644 --- a/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja +++ b/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja @@ -20,6 +20,11 @@ code in a proprietary work, I am not going to enforce this in court. #} {% extends "base.html.jinja" %} +{% macro hkt_doc_link(page_name) %} + {% set doc_url = 'https://hkt.mitm.it/doc/' ~ page_name %} + {{ doc_link(doc_url) }} +{% endmacro %} + {% block style %} {{ super() }} @@ -47,7 +52,9 @@ code in a proprietary work, I am not going to enforce this in court.
- {{ label(_('info.base.page_policy_label')) }} + {% call label(_('info.base.page_policy_label')) %} + {{ hkt_doc_link('policy_selection') }} + {% endcall %}

{% block site_policy required %}{% endblock %} diff --git a/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja index b808827..1c0c662 100644 --- a/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja +++ b/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja @@ -29,7 +29,9 @@ code in a proprietary work, I am not going to enforce this in court. {% block main_rest %}

- {{ label(_('info.rule.matched_pattern_label')) }} + {% call label(_('info.rule.matched_pattern_label')) %} + {{ hkt_doc_link('url_patterns') }} + {% endcall %}

{{ pattern }} diff --git a/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja index a71ca25..e66e685 100644 --- a/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja +++ b/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja @@ -40,7 +40,9 @@ code in a proprietary work, I am not going to enforce this in court. {% block main_rest %}

- {{ label(_('info.payload.matched_pattern_label')) }} + {% call label(_('info.payload.matched_pattern_label')) %} + {{ hkt_doc_link('url_patterns') }} + {% endcall %}

{{ payload_data.pattern }} diff --git a/src/hydrilla/proxy/self_doc.py b/src/hydrilla/proxy/self_doc.py index a1a2485..ccf0e12 100644 --- a/src/hydrilla/proxy/self_doc.py +++ b/src/hydrilla/proxy/self_doc.py @@ -8,4 +8,4 @@ import jinja2 loader = jinja2.PackageLoader(__package__, package_path='self_doc') -page_names = {'url_patterns'} +page_names = {'url_patterns', 'policy_selection'} diff --git a/src/hydrilla/proxy/self_doc/doc_base.html.jinja b/src/hydrilla/proxy/self_doc/doc_base.html.jinja index 7982142..71842f2 100644 --- a/src/hydrilla/proxy/self_doc/doc_base.html.jinja +++ b/src/hydrilla/proxy/self_doc/doc_base.html.jinja @@ -36,8 +36,20 @@ code in a proprietary work, I am not going to enforce this in court. {{ caller()|safe }} {% endmacro %} -{% macro link(where, text) -%} - {{ text }} +{% macro doc_page_link(text, page_name) -%} + {% if doc_output == 'html_hkt_mitm_it' -%} + {{ text }} + {%- else -%} + {{ text }} + {%- endif %} +{%- endmacro %} + +{% macro hkt_link(text, endpoint_name) -%} + {% if doc_output == 'html_hkt_mitm_it' -%} + {{ text }} + {%- else -%} + {{ text }} + {%- endif %} {%- endmacro %} {% macro paragraph() %} diff --git a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja new file mode 100644 index 0000000..6519e42 --- /dev/null +++ b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja @@ -0,0 +1,87 @@ +{# +SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 + +Documentation page describing how Haketilo selects policy to apply to a page. + +This file is part of Hydrilla&Haketilo. + +Copyright (C) 2022 Wojtek Kosior + +Dual licensed under +* GNU General Public License v3.0 or later and +* Creative Commons Attribution Share Alike 4.0 International. + +You can choose to use either of these licenses or both. + + +I, Wojtek Kosior, thereby promise not to sue for violation of this +file's licenses. Although I request that you do not make use of this +code in a proprietary work, I am not going to enforce this in court. +#} +{% extends "doc_base.html.jinja" %} + +{% block title %}{{ _('doc.policy_selection.title') }}{% endblock %} + +{% block main %} + {{ big_heading(_('doc.policy_selection.h_big')) }} + + {% call section() %} + {% call paragraph() %} + {{ _('doc.policy_selection.intro') }} + {% call unordered_list() %} + {% call list_entry() %} + {{ _('doc.policy_selection.enabled_payload_case') }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.policy_selection.auto_payload_case') }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.policy_selection.ask_payload_case') }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.policy_selection.block_js_case') }} + {% endcall %} + {% call list_entry() %} + {{ _('doc.policy_selection.allow_js_case') }} + {% endcall %} + {% endcall %} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading(_('doc.policy_selection.h_medium.precedence')) }} + + {% call paragraph() %} + {% set fmt = _('doc.policy_selection.html.precedence_general_{patterns_link}') %} + {% set link_text = _('doc.policy_selection.precedence_general.patterns_link_text') %} + {% set link = doc_page_link(link_text|e, 'url_patterns') %} + {{ fmt.format(patterns_link=link)|safe }} + {% endcall %} + + {% call paragraph() %} + {% set fmt = _('doc.policy_selection.html.precedence_nonenabled_{settings_link}') %} + {% set link_text = _('doc.policy_selection.precedence_nonenabled.settings_link_text') %} + {% set link = hkt_link(link_text|e, 'home.home') %} + {{ fmt.format(settings_link=link)|safe }} + {% endcall %} + + {% call paragraph() %} + {% set fmt = _('doc.policy_selection.html.precedence_fallback_{settings_link}') %} + {% set link_text = _('doc.policy_selection.precedence_fallback.settings_link_text') %} + {% set link = hkt_link(link_text|e, 'home.home') %} + {{ fmt.format(settings_link=link)|safe }} + {% endcall %} + {% endcall %} + + {% call section() %} + {{ medium_heading(_('doc.policy_selection.special_cases.h_medium')) }} + + {% call paragraph() %} + {{ _('doc.policy_selection.special_cases.html.exepmt_and_error')|safe }} + {% endcall %} + + {% call paragraph() %} + {{ _('doc.policy_selection.special_cases.internal_policies') }} + {% endcall %} + {% endcall %} +{% endblock main %} -- cgit v1.2.3