Fossil SCM
Add documentation regarding tainted strings in TH1. Mention the introduction of tainted strings in the 2.25 change log.
Commit
90b63bc5d142d1eaa326e205bb8e15268681338dd7f5e0c7f570e4b72fda1de9
Parent
5291edac072416b…
2 files changed
+7
+87
-6
+7
| --- www/changes.wiki | ||
| +++ www/changes.wiki | ||
| @@ -138,10 +138,17 @@ | ||
| 138 | 138 | when a user's permissions change. |
| 139 | 139 | * Show project description on repository list. |
| 140 | 140 | * Make [/help?cmd=/chat|/chat] better-behaved during server outages, reducing |
| 141 | 141 | the frequency of reconnection attempts over time and providing feedback |
| 142 | 142 | to the user when the connection is down. |
| 143 | + * The [/doc/trunk/www/th1.md|TH1 script language] now makes a distinction | |
| 144 | + between [/doc/trunk/www/th1.md#taint|tainted and untainted string values]. | |
| 145 | + This is a security enhancement that makes it more difficult to write | |
| 146 | + custom TH1 scripts that contain XSS or SQL-injection bugs. As part of | |
| 147 | + this enhancement, the [/help?cmd=vuln-report|vuln-report] setting was | |
| 148 | + added to control what Fossil does when it encounters a potential TH1 | |
| 149 | + security problem. | |
| 143 | 150 | * Diverse minor fixes and additions. |
| 144 | 151 | |
| 145 | 152 | |
| 146 | 153 | <h2 id='v2_25'>Changes for version 2.25 (2024-11-06)</h2> |
| 147 | 154 | |
| 148 | 155 |
| --- www/changes.wiki | |
| +++ www/changes.wiki | |
| @@ -138,10 +138,17 @@ | |
| 138 | when a user's permissions change. |
| 139 | * Show project description on repository list. |
| 140 | * Make [/help?cmd=/chat|/chat] better-behaved during server outages, reducing |
| 141 | the frequency of reconnection attempts over time and providing feedback |
| 142 | to the user when the connection is down. |
| 143 | * Diverse minor fixes and additions. |
| 144 | |
| 145 | |
| 146 | <h2 id='v2_25'>Changes for version 2.25 (2024-11-06)</h2> |
| 147 | |
| 148 |
| --- www/changes.wiki | |
| +++ www/changes.wiki | |
| @@ -138,10 +138,17 @@ | |
| 138 | when a user's permissions change. |
| 139 | * Show project description on repository list. |
| 140 | * Make [/help?cmd=/chat|/chat] better-behaved during server outages, reducing |
| 141 | the frequency of reconnection attempts over time and providing feedback |
| 142 | to the user when the connection is down. |
| 143 | * The [/doc/trunk/www/th1.md|TH1 script language] now makes a distinction |
| 144 | between [/doc/trunk/www/th1.md#taint|tainted and untainted string values]. |
| 145 | This is a security enhancement that makes it more difficult to write |
| 146 | custom TH1 scripts that contain XSS or SQL-injection bugs. As part of |
| 147 | this enhancement, the [/help?cmd=vuln-report|vuln-report] setting was |
| 148 | added to control what Fossil does when it encounters a potential TH1 |
| 149 | security problem. |
| 150 | * Diverse minor fixes and additions. |
| 151 | |
| 152 | |
| 153 | <h2 id='v2_25'>Changes for version 2.25 (2024-11-06)</h2> |
| 154 | |
| 155 |
+87
-6
| --- www/th1.md | ||
| +++ www/th1.md | ||
| @@ -68,11 +68,11 @@ | ||
| 68 | 68 | are removed from each token by the command parser.) The third token |
| 69 | 69 | is the `puts "hello"`, with its whitespace and newlines. The fourth token |
| 70 | 70 | is `else` and the fifth and last token is `puts "world"`. |
| 71 | 71 | |
| 72 | 72 | The `if` command evaluates its first argument (the second token) |
| 73 | -as an expression, and if that expression is true, evaluates its | |
| 73 | +as an expression, and if that expression is true, it evaluates its | |
| 74 | 74 | second argument (the third token) as a TH1 script. |
| 75 | 75 | If the expression is false and the third argument is `else`, then |
| 76 | 76 | the fourth argument is evaluated as a TH1 expression. |
| 77 | 77 | |
| 78 | 78 | So, you see, even though the example above spans five lines, it is really |
| @@ -106,10 +106,49 @@ | ||
| 106 | 106 | $repository "" info trunk]]] end] |
| 107 | 107 | |
| 108 | 108 | Those backslashes allow the command to wrap nicely within a standard |
| 109 | 109 | terminal width while telling the interpreter to consider those three |
| 110 | 110 | lines as a single command. |
| 111 | + | |
| 112 | +<a id="taint"></a>Tainted And Untainted Strings | |
| 113 | +----------------------------------------------- | |
| 114 | + | |
| 115 | +Beginning with Fossil version 2.25 (circa 2025), TH1 distinguishes between | |
| 116 | +"tainted" and "untainted" strings. Tainted strings are strings that are | |
| 117 | +derived from user inputs that might contain text that is designed to subvert | |
| 118 | +the script. Untainted strings are known to come from secure sources and | |
| 119 | +are assumed to contain no malicious content. | |
| 120 | + | |
| 121 | +Beginning with Fossil version 2.25, and depending on the value of the | |
| 122 | +[vuln-report setting](/help?cmd=vuln-report), TH1 will prevent tainted | |
| 123 | +strings from being used in ways that might lead to XSS or SQL-injection | |
| 124 | +attacks. This feature helps to ensure that XSS and SQL-injection | |
| 125 | +vulnerabilities are not *accidentally* added to Fossil when | |
| 126 | +custom TH1 scripts for headers or footers or tickets are added to a | |
| 127 | +repository. Note that the tainted/untainted distinction in strings does | |
| 128 | +make it impossible to introduce XSS and SQL-injections vulnerabilities | |
| 129 | +using poorly-written TH1 scripts; it just makes it more difficult and | |
| 130 | +less likely to happen by accident. Developers must still consider the | |
| 131 | +security implications TH1 customizations they add to Fossil, and take | |
| 132 | +appropriate precautions when writing custom TH1. Peer review of TH1 | |
| 133 | +script changes is encouraged. | |
| 134 | + | |
| 135 | +In Fossil version 2.25, if the vuln-report setting is set to "block" | |
| 136 | +or "fatal", the [html](#html) and [query](#query) TH1 commands will | |
| 137 | +fail with an error if their argument is a tainted string. This helps | |
| 138 | +to prevent XSS and SQL-injection attacks, respectively. Note that | |
| 139 | +the default value of the vuln-report setting is "log", which allows those | |
| 140 | +commands to continue working and only writes a warning message into the | |
| 141 | +error log. <b>Future versions of Fossil may change the default value | |
| 142 | +of the vuln-report setting to "block" or "fatal".</b> Fossil users | |
| 143 | +with customized TH1 scripts are encouraged to audit their customizations | |
| 144 | +and fix any potential vulnerabilities soon, so as to avoid breakage | |
| 145 | +caused by future upgrades. <b>Future versions of Fossil might also | |
| 146 | +place additional restrictions on the use of tainted strings.</b> | |
| 147 | +For example, it is likely that future versions of Fossil will disallow | |
| 148 | +using tainted strings as script, for example as the body of a "for" | |
| 149 | +loop or of a "proc". | |
| 111 | 150 | |
| 112 | 151 | |
| 113 | 152 | Summary of Core TH1 Commands |
| 114 | 153 | ---------------------------- |
| 115 | 154 | |
| @@ -147,10 +186,13 @@ | ||
| 147 | 186 | * string last NEEDLE HAYSTACK ?START-INDEX? |
| 148 | 187 | * string match PATTERN STRING |
| 149 | 188 | * string length STRING |
| 150 | 189 | * string range STRING FIRST LAST |
| 151 | 190 | * string repeat STRING COUNT |
| 191 | + * string trim STRING | |
| 192 | + * string trimleft STRING | |
| 193 | + * string trimright STRING | |
| 152 | 194 | * unset VARNAME |
| 153 | 195 | * uplevel ?LEVEL? SCRIPT |
| 154 | 196 | * upvar ?FRAME? OTHERVAR MYVAR ?OTHERVAR MYVAR? |
| 155 | 197 | |
| 156 | 198 | All of the above commands work as in the original Tcl. Refer to the |
| @@ -214,17 +256,19 @@ | ||
| 214 | 256 | * [stime](#stime) |
| 215 | 257 | * [styleHeader](#styleHeader) |
| 216 | 258 | * [styleFooter](#styleFooter) |
| 217 | 259 | * [styleScript](#styleScript) |
| 218 | 260 | * [submenu](#submenu) |
| 261 | + * [taint](#taintCmd) | |
| 219 | 262 | * [tclEval](#tclEval) |
| 220 | 263 | * [tclExpr](#tclExpr) |
| 221 | 264 | * [tclInvoke](#tclInvoke) |
| 222 | 265 | * [tclIsSafe](#tclIsSafe) |
| 223 | 266 | * [tclMakeSafe](#tclMakeSafe) |
| 224 | 267 | * [tclReady](#tclReady) |
| 225 | 268 | * [trace](#trace) |
| 269 | + * [untaint](#untaintCmd) | |
| 226 | 270 | * [unversioned content](#unversioned_content) |
| 227 | 271 | * [unversioned list](#unversioned_list) |
| 228 | 272 | * [utime](#utime) |
| 229 | 273 | * [verifyCsrf](#verifyCsrf) |
| 230 | 274 | * [verifyLogin](#verifyLogin) |
| @@ -528,22 +572,24 @@ | ||
| 528 | 572 | ----------------------------------- |
| 529 | 573 | |
| 530 | 574 | * html STRING |
| 531 | 575 | |
| 532 | 576 | Outputs the STRING literally. It is assumed that STRING contains |
| 533 | -valid HTML, or that if it text then any characters that are | |
| 577 | +valid HTML, or that if STRING contains any characters that are | |
| 534 | 578 | significant to HTML (such as `<`, `>`, `'`, or `&`) have already |
| 535 | -been escaped, perhaps by the htmlize command. Use the | |
| 579 | +been escaped, perhaps by the [htmlize](#htmlize) command. Use the | |
| 536 | 580 | [puts](#puts) command to output text that might contain unescaped |
| 537 | 581 | HTML markup. |
| 538 | 582 | |
| 539 | 583 | **Beware of XSS attacks!** If the STRING value to the html command |
| 540 | 584 | can be controlled by a hostile user, then he might be able to sneak |
| 541 | 585 | in malicious HTML or Javascript which could result in a |
| 542 | 586 | cross-site scripting (XSS) attack. Be careful that all text that |
| 543 | 587 | in STRING that might come from user input has been sanitized by the |
| 544 | -[htmlize](#htmlize) command or similar. | |
| 588 | +[htmlize](#htmlize) command or similar. In recent versions of Fossil, | |
| 589 | +the STRING value must be [untainted](#taint) or else the "html" command | |
| 590 | +will fail. | |
| 545 | 591 | |
| 546 | 592 | <a id="htmlize"></a>TH1 htmlize Command |
| 547 | 593 | ----------------------------------------- |
| 548 | 594 | |
| 549 | 595 | * htmlize STRING |
| @@ -610,11 +656,13 @@ | ||
| 610 | 656 | * puts STRING |
| 611 | 657 | |
| 612 | 658 | Outputs STRING. Characters within STRING that have special meaning |
| 613 | 659 | in HTML are escaped prior to being output. Thus is it safe for STRING |
| 614 | 660 | to be derived from user inputs. See also the [html](#html) command |
| 615 | -which behaves similarly except does not escape HTML markup. | |
| 661 | +which behaves similarly except does not escape HTML markup. This | |
| 662 | +command ("puts") is safe to use on [tainted strings](#taint), but the "html" | |
| 663 | +command is not. | |
| 616 | 664 | |
| 617 | 665 | <a id="query"></a>TH1 query Command |
| 618 | 666 | ------------------------------------- |
| 619 | 667 | |
| 620 | 668 | * query ?-nocomplain? SQL CODE |
| @@ -622,11 +670,14 @@ | ||
| 622 | 670 | Runs the SQL query given by the SQL argument. For each row in the result |
| 623 | 671 | set, run CODE. |
| 624 | 672 | |
| 625 | 673 | In SQL, parameters such as $var are filled in using the value of variable |
| 626 | 674 | "var". Result values are stored in variables with the column name prior |
| 627 | -to each invocation of CODE. | |
| 675 | +to each invocation of CODE. The names of the variables in which results | |
| 676 | +are stored can be controlled using "AS name" clauses in the SQL. As | |
| 677 | +the database will often contain content that originates from untrusted | |
| 678 | +users, all result values are marked as [tainted](#taint). | |
| 628 | 679 | |
| 629 | 680 | **Beware of SQL injections in the `query` command!** |
| 630 | 681 | The SQL argument to the query command should always be literal SQL |
| 631 | 682 | text enclosed in {...}. The SQL argument should never be a double-quoted |
| 632 | 683 | string or the value of a \$variable, as those constructs can lead to |
| @@ -649,10 +700,14 @@ | ||
| 649 | 700 | ~~~ |
| 650 | 701 | |
| 651 | 702 | In this second example, TH1 does the expansion of `$mykey` prior to passing |
| 652 | 703 | the text down into SQLite. So if `$mykey` contains a single-quote character, |
| 653 | 704 | followed by additional hostile text, that will result in an SQL injection. |
| 705 | + | |
| 706 | +To help guard against SQL-injections, recent versions of Fossil require | |
| 707 | +that the SQL argument be [untainted](#taint) or else the "query" command | |
| 708 | +will fail. | |
| 654 | 709 | |
| 655 | 710 | <a id="randhex"></a>TH1 randhex Command |
| 656 | 711 | ----------------------------------------- |
| 657 | 712 | |
| 658 | 713 | * randhex N |
| @@ -783,10 +838,24 @@ | ||
| 783 | 838 | |
| 784 | 839 | * submenu link LABEL URL |
| 785 | 840 | |
| 786 | 841 | Add hyperlink to the submenu of the current page. |
| 787 | 842 | |
| 843 | +<a id="taintCmd"></a>TH1 taint Command | |
| 844 | +----------------------------------------- | |
| 845 | + | |
| 846 | + * taint STRING | |
| 847 | + | |
| 848 | +This command returns a copy of STRING that has been marked as | |
| 849 | +[tainted](#taint). Tainted strings are strings which might be | |
| 850 | +controlled by an attacker and might contain hostile inputs and | |
| 851 | +are thus unsafe to use in certain contexts. For example, tainted | |
| 852 | +strings should not be output as part of a webpage as they might | |
| 853 | +contain rogue HTML or Javascript that could lead to an XSS | |
| 854 | +vulnerability. Similarly, tainted strings should not be run as | |
| 855 | +SQL since they might contain an SQL-injection vulerability. | |
| 856 | + | |
| 788 | 857 | <a id="tclEval"></a>TH1 tclEval Command |
| 789 | 858 | ----------------------------------------- |
| 790 | 859 | |
| 791 | 860 | **This command requires the Tcl integration feature.** |
| 792 | 861 | |
| @@ -854,10 +923,22 @@ | ||
| 854 | 923 | |
| 855 | 924 | * trace STRING |
| 856 | 925 | |
| 857 | 926 | Generates a TH1 trace message if TH1 tracing is enabled. |
| 858 | 927 | |
| 928 | +<a id="untaintCmd"></a>TH1 taint Command | |
| 929 | +----------------------------------------- | |
| 930 | + | |
| 931 | + * untaint STRING | |
| 932 | + | |
| 933 | +This command returns a copy of STRING that has been marked as | |
| 934 | +[untainted](#taint). Untainted strings are strings which are | |
| 935 | +believed to be free of potentially hostile content. Use this | |
| 936 | +command with caution, as it overwrites the tainted-string protection | |
| 937 | +mechanisms that are built into TH1. If you do not understand all | |
| 938 | +the implications of executing this command, then do not use it. | |
| 939 | + | |
| 859 | 940 | <a id="unversioned_content"></a>TH1 unversioned content Command |
| 860 | 941 | ----------------------------------------------------------------- |
| 861 | 942 | |
| 862 | 943 | * unversioned content FILENAME |
| 863 | 944 | |
| 864 | 945 |
| --- www/th1.md | |
| +++ www/th1.md | |
| @@ -68,11 +68,11 @@ | |
| 68 | are removed from each token by the command parser.) The third token |
| 69 | is the `puts "hello"`, with its whitespace and newlines. The fourth token |
| 70 | is `else` and the fifth and last token is `puts "world"`. |
| 71 | |
| 72 | The `if` command evaluates its first argument (the second token) |
| 73 | as an expression, and if that expression is true, evaluates its |
| 74 | second argument (the third token) as a TH1 script. |
| 75 | If the expression is false and the third argument is `else`, then |
| 76 | the fourth argument is evaluated as a TH1 expression. |
| 77 | |
| 78 | So, you see, even though the example above spans five lines, it is really |
| @@ -106,10 +106,49 @@ | |
| 106 | $repository "" info trunk]]] end] |
| 107 | |
| 108 | Those backslashes allow the command to wrap nicely within a standard |
| 109 | terminal width while telling the interpreter to consider those three |
| 110 | lines as a single command. |
| 111 | |
| 112 | |
| 113 | Summary of Core TH1 Commands |
| 114 | ---------------------------- |
| 115 | |
| @@ -147,10 +186,13 @@ | |
| 147 | * string last NEEDLE HAYSTACK ?START-INDEX? |
| 148 | * string match PATTERN STRING |
| 149 | * string length STRING |
| 150 | * string range STRING FIRST LAST |
| 151 | * string repeat STRING COUNT |
| 152 | * unset VARNAME |
| 153 | * uplevel ?LEVEL? SCRIPT |
| 154 | * upvar ?FRAME? OTHERVAR MYVAR ?OTHERVAR MYVAR? |
| 155 | |
| 156 | All of the above commands work as in the original Tcl. Refer to the |
| @@ -214,17 +256,19 @@ | |
| 214 | * [stime](#stime) |
| 215 | * [styleHeader](#styleHeader) |
| 216 | * [styleFooter](#styleFooter) |
| 217 | * [styleScript](#styleScript) |
| 218 | * [submenu](#submenu) |
| 219 | * [tclEval](#tclEval) |
| 220 | * [tclExpr](#tclExpr) |
| 221 | * [tclInvoke](#tclInvoke) |
| 222 | * [tclIsSafe](#tclIsSafe) |
| 223 | * [tclMakeSafe](#tclMakeSafe) |
| 224 | * [tclReady](#tclReady) |
| 225 | * [trace](#trace) |
| 226 | * [unversioned content](#unversioned_content) |
| 227 | * [unversioned list](#unversioned_list) |
| 228 | * [utime](#utime) |
| 229 | * [verifyCsrf](#verifyCsrf) |
| 230 | * [verifyLogin](#verifyLogin) |
| @@ -528,22 +572,24 @@ | |
| 528 | ----------------------------------- |
| 529 | |
| 530 | * html STRING |
| 531 | |
| 532 | Outputs the STRING literally. It is assumed that STRING contains |
| 533 | valid HTML, or that if it text then any characters that are |
| 534 | significant to HTML (such as `<`, `>`, `'`, or `&`) have already |
| 535 | been escaped, perhaps by the htmlize command. Use the |
| 536 | [puts](#puts) command to output text that might contain unescaped |
| 537 | HTML markup. |
| 538 | |
| 539 | **Beware of XSS attacks!** If the STRING value to the html command |
| 540 | can be controlled by a hostile user, then he might be able to sneak |
| 541 | in malicious HTML or Javascript which could result in a |
| 542 | cross-site scripting (XSS) attack. Be careful that all text that |
| 543 | in STRING that might come from user input has been sanitized by the |
| 544 | [htmlize](#htmlize) command or similar. |
| 545 | |
| 546 | <a id="htmlize"></a>TH1 htmlize Command |
| 547 | ----------------------------------------- |
| 548 | |
| 549 | * htmlize STRING |
| @@ -610,11 +656,13 @@ | |
| 610 | * puts STRING |
| 611 | |
| 612 | Outputs STRING. Characters within STRING that have special meaning |
| 613 | in HTML are escaped prior to being output. Thus is it safe for STRING |
| 614 | to be derived from user inputs. See also the [html](#html) command |
| 615 | which behaves similarly except does not escape HTML markup. |
| 616 | |
| 617 | <a id="query"></a>TH1 query Command |
| 618 | ------------------------------------- |
| 619 | |
| 620 | * query ?-nocomplain? SQL CODE |
| @@ -622,11 +670,14 @@ | |
| 622 | Runs the SQL query given by the SQL argument. For each row in the result |
| 623 | set, run CODE. |
| 624 | |
| 625 | In SQL, parameters such as $var are filled in using the value of variable |
| 626 | "var". Result values are stored in variables with the column name prior |
| 627 | to each invocation of CODE. |
| 628 | |
| 629 | **Beware of SQL injections in the `query` command!** |
| 630 | The SQL argument to the query command should always be literal SQL |
| 631 | text enclosed in {...}. The SQL argument should never be a double-quoted |
| 632 | string or the value of a \$variable, as those constructs can lead to |
| @@ -649,10 +700,14 @@ | |
| 649 | ~~~ |
| 650 | |
| 651 | In this second example, TH1 does the expansion of `$mykey` prior to passing |
| 652 | the text down into SQLite. So if `$mykey` contains a single-quote character, |
| 653 | followed by additional hostile text, that will result in an SQL injection. |
| 654 | |
| 655 | <a id="randhex"></a>TH1 randhex Command |
| 656 | ----------------------------------------- |
| 657 | |
| 658 | * randhex N |
| @@ -783,10 +838,24 @@ | |
| 783 | |
| 784 | * submenu link LABEL URL |
| 785 | |
| 786 | Add hyperlink to the submenu of the current page. |
| 787 | |
| 788 | <a id="tclEval"></a>TH1 tclEval Command |
| 789 | ----------------------------------------- |
| 790 | |
| 791 | **This command requires the Tcl integration feature.** |
| 792 | |
| @@ -854,10 +923,22 @@ | |
| 854 | |
| 855 | * trace STRING |
| 856 | |
| 857 | Generates a TH1 trace message if TH1 tracing is enabled. |
| 858 | |
| 859 | <a id="unversioned_content"></a>TH1 unversioned content Command |
| 860 | ----------------------------------------------------------------- |
| 861 | |
| 862 | * unversioned content FILENAME |
| 863 | |
| 864 |
| --- www/th1.md | |
| +++ www/th1.md | |
| @@ -68,11 +68,11 @@ | |
| 68 | are removed from each token by the command parser.) The third token |
| 69 | is the `puts "hello"`, with its whitespace and newlines. The fourth token |
| 70 | is `else` and the fifth and last token is `puts "world"`. |
| 71 | |
| 72 | The `if` command evaluates its first argument (the second token) |
| 73 | as an expression, and if that expression is true, it evaluates its |
| 74 | second argument (the third token) as a TH1 script. |
| 75 | If the expression is false and the third argument is `else`, then |
| 76 | the fourth argument is evaluated as a TH1 expression. |
| 77 | |
| 78 | So, you see, even though the example above spans five lines, it is really |
| @@ -106,10 +106,49 @@ | |
| 106 | $repository "" info trunk]]] end] |
| 107 | |
| 108 | Those backslashes allow the command to wrap nicely within a standard |
| 109 | terminal width while telling the interpreter to consider those three |
| 110 | lines as a single command. |
| 111 | |
| 112 | <a id="taint"></a>Tainted And Untainted Strings |
| 113 | ----------------------------------------------- |
| 114 | |
| 115 | Beginning with Fossil version 2.25 (circa 2025), TH1 distinguishes between |
| 116 | "tainted" and "untainted" strings. Tainted strings are strings that are |
| 117 | derived from user inputs that might contain text that is designed to subvert |
| 118 | the script. Untainted strings are known to come from secure sources and |
| 119 | are assumed to contain no malicious content. |
| 120 | |
| 121 | Beginning with Fossil version 2.25, and depending on the value of the |
| 122 | [vuln-report setting](/help?cmd=vuln-report), TH1 will prevent tainted |
| 123 | strings from being used in ways that might lead to XSS or SQL-injection |
| 124 | attacks. This feature helps to ensure that XSS and SQL-injection |
| 125 | vulnerabilities are not *accidentally* added to Fossil when |
| 126 | custom TH1 scripts for headers or footers or tickets are added to a |
| 127 | repository. Note that the tainted/untainted distinction in strings does |
| 128 | make it impossible to introduce XSS and SQL-injections vulnerabilities |
| 129 | using poorly-written TH1 scripts; it just makes it more difficult and |
| 130 | less likely to happen by accident. Developers must still consider the |
| 131 | security implications TH1 customizations they add to Fossil, and take |
| 132 | appropriate precautions when writing custom TH1. Peer review of TH1 |
| 133 | script changes is encouraged. |
| 134 | |
| 135 | In Fossil version 2.25, if the vuln-report setting is set to "block" |
| 136 | or "fatal", the [html](#html) and [query](#query) TH1 commands will |
| 137 | fail with an error if their argument is a tainted string. This helps |
| 138 | to prevent XSS and SQL-injection attacks, respectively. Note that |
| 139 | the default value of the vuln-report setting is "log", which allows those |
| 140 | commands to continue working and only writes a warning message into the |
| 141 | error log. <b>Future versions of Fossil may change the default value |
| 142 | of the vuln-report setting to "block" or "fatal".</b> Fossil users |
| 143 | with customized TH1 scripts are encouraged to audit their customizations |
| 144 | and fix any potential vulnerabilities soon, so as to avoid breakage |
| 145 | caused by future upgrades. <b>Future versions of Fossil might also |
| 146 | place additional restrictions on the use of tainted strings.</b> |
| 147 | For example, it is likely that future versions of Fossil will disallow |
| 148 | using tainted strings as script, for example as the body of a "for" |
| 149 | loop or of a "proc". |
| 150 | |
| 151 | |
| 152 | Summary of Core TH1 Commands |
| 153 | ---------------------------- |
| 154 | |
| @@ -147,10 +186,13 @@ | |
| 186 | * string last NEEDLE HAYSTACK ?START-INDEX? |
| 187 | * string match PATTERN STRING |
| 188 | * string length STRING |
| 189 | * string range STRING FIRST LAST |
| 190 | * string repeat STRING COUNT |
| 191 | * string trim STRING |
| 192 | * string trimleft STRING |
| 193 | * string trimright STRING |
| 194 | * unset VARNAME |
| 195 | * uplevel ?LEVEL? SCRIPT |
| 196 | * upvar ?FRAME? OTHERVAR MYVAR ?OTHERVAR MYVAR? |
| 197 | |
| 198 | All of the above commands work as in the original Tcl. Refer to the |
| @@ -214,17 +256,19 @@ | |
| 256 | * [stime](#stime) |
| 257 | * [styleHeader](#styleHeader) |
| 258 | * [styleFooter](#styleFooter) |
| 259 | * [styleScript](#styleScript) |
| 260 | * [submenu](#submenu) |
| 261 | * [taint](#taintCmd) |
| 262 | * [tclEval](#tclEval) |
| 263 | * [tclExpr](#tclExpr) |
| 264 | * [tclInvoke](#tclInvoke) |
| 265 | * [tclIsSafe](#tclIsSafe) |
| 266 | * [tclMakeSafe](#tclMakeSafe) |
| 267 | * [tclReady](#tclReady) |
| 268 | * [trace](#trace) |
| 269 | * [untaint](#untaintCmd) |
| 270 | * [unversioned content](#unversioned_content) |
| 271 | * [unversioned list](#unversioned_list) |
| 272 | * [utime](#utime) |
| 273 | * [verifyCsrf](#verifyCsrf) |
| 274 | * [verifyLogin](#verifyLogin) |
| @@ -528,22 +572,24 @@ | |
| 572 | ----------------------------------- |
| 573 | |
| 574 | * html STRING |
| 575 | |
| 576 | Outputs the STRING literally. It is assumed that STRING contains |
| 577 | valid HTML, or that if STRING contains any characters that are |
| 578 | significant to HTML (such as `<`, `>`, `'`, or `&`) have already |
| 579 | been escaped, perhaps by the [htmlize](#htmlize) command. Use the |
| 580 | [puts](#puts) command to output text that might contain unescaped |
| 581 | HTML markup. |
| 582 | |
| 583 | **Beware of XSS attacks!** If the STRING value to the html command |
| 584 | can be controlled by a hostile user, then he might be able to sneak |
| 585 | in malicious HTML or Javascript which could result in a |
| 586 | cross-site scripting (XSS) attack. Be careful that all text that |
| 587 | in STRING that might come from user input has been sanitized by the |
| 588 | [htmlize](#htmlize) command or similar. In recent versions of Fossil, |
| 589 | the STRING value must be [untainted](#taint) or else the "html" command |
| 590 | will fail. |
| 591 | |
| 592 | <a id="htmlize"></a>TH1 htmlize Command |
| 593 | ----------------------------------------- |
| 594 | |
| 595 | * htmlize STRING |
| @@ -610,11 +656,13 @@ | |
| 656 | * puts STRING |
| 657 | |
| 658 | Outputs STRING. Characters within STRING that have special meaning |
| 659 | in HTML are escaped prior to being output. Thus is it safe for STRING |
| 660 | to be derived from user inputs. See also the [html](#html) command |
| 661 | which behaves similarly except does not escape HTML markup. This |
| 662 | command ("puts") is safe to use on [tainted strings](#taint), but the "html" |
| 663 | command is not. |
| 664 | |
| 665 | <a id="query"></a>TH1 query Command |
| 666 | ------------------------------------- |
| 667 | |
| 668 | * query ?-nocomplain? SQL CODE |
| @@ -622,11 +670,14 @@ | |
| 670 | Runs the SQL query given by the SQL argument. For each row in the result |
| 671 | set, run CODE. |
| 672 | |
| 673 | In SQL, parameters such as $var are filled in using the value of variable |
| 674 | "var". Result values are stored in variables with the column name prior |
| 675 | to each invocation of CODE. The names of the variables in which results |
| 676 | are stored can be controlled using "AS name" clauses in the SQL. As |
| 677 | the database will often contain content that originates from untrusted |
| 678 | users, all result values are marked as [tainted](#taint). |
| 679 | |
| 680 | **Beware of SQL injections in the `query` command!** |
| 681 | The SQL argument to the query command should always be literal SQL |
| 682 | text enclosed in {...}. The SQL argument should never be a double-quoted |
| 683 | string or the value of a \$variable, as those constructs can lead to |
| @@ -649,10 +700,14 @@ | |
| 700 | ~~~ |
| 701 | |
| 702 | In this second example, TH1 does the expansion of `$mykey` prior to passing |
| 703 | the text down into SQLite. So if `$mykey` contains a single-quote character, |
| 704 | followed by additional hostile text, that will result in an SQL injection. |
| 705 | |
| 706 | To help guard against SQL-injections, recent versions of Fossil require |
| 707 | that the SQL argument be [untainted](#taint) or else the "query" command |
| 708 | will fail. |
| 709 | |
| 710 | <a id="randhex"></a>TH1 randhex Command |
| 711 | ----------------------------------------- |
| 712 | |
| 713 | * randhex N |
| @@ -783,10 +838,24 @@ | |
| 838 | |
| 839 | * submenu link LABEL URL |
| 840 | |
| 841 | Add hyperlink to the submenu of the current page. |
| 842 | |
| 843 | <a id="taintCmd"></a>TH1 taint Command |
| 844 | ----------------------------------------- |
| 845 | |
| 846 | * taint STRING |
| 847 | |
| 848 | This command returns a copy of STRING that has been marked as |
| 849 | [tainted](#taint). Tainted strings are strings which might be |
| 850 | controlled by an attacker and might contain hostile inputs and |
| 851 | are thus unsafe to use in certain contexts. For example, tainted |
| 852 | strings should not be output as part of a webpage as they might |
| 853 | contain rogue HTML or Javascript that could lead to an XSS |
| 854 | vulnerability. Similarly, tainted strings should not be run as |
| 855 | SQL since they might contain an SQL-injection vulerability. |
| 856 | |
| 857 | <a id="tclEval"></a>TH1 tclEval Command |
| 858 | ----------------------------------------- |
| 859 | |
| 860 | **This command requires the Tcl integration feature.** |
| 861 | |
| @@ -854,10 +923,22 @@ | |
| 923 | |
| 924 | * trace STRING |
| 925 | |
| 926 | Generates a TH1 trace message if TH1 tracing is enabled. |
| 927 | |
| 928 | <a id="untaintCmd"></a>TH1 taint Command |
| 929 | ----------------------------------------- |
| 930 | |
| 931 | * untaint STRING |
| 932 | |
| 933 | This command returns a copy of STRING that has been marked as |
| 934 | [untainted](#taint). Untainted strings are strings which are |
| 935 | believed to be free of potentially hostile content. Use this |
| 936 | command with caution, as it overwrites the tainted-string protection |
| 937 | mechanisms that are built into TH1. If you do not understand all |
| 938 | the implications of executing this command, then do not use it. |
| 939 | |
| 940 | <a id="unversioned_content"></a>TH1 unversioned content Command |
| 941 | ----------------------------------------------------------------- |
| 942 | |
| 943 | * unversioned content FILENAME |
| 944 | |
| 945 |