Skip to content

Commit 08a5bf3

Browse files
TheSyscallTheSyscall
committed
Document Security configuration page, CSP options and CspHook
Adds a Security Configuration section to 03-Configuration.md covering all new config.ini keys (use_custom_csp, custom_csp, csp_enable_modules, csp_enable_dashboards, csp_enable_navigation). Expands the CSP section in 20-Advanced-Topics.md to explain per-source controls, the CspHook extension point and the custom CSP override, including the {style_nonce} placeholder. Adds a CspHook reference entry with an example implementation to 60-Hooks.md.
1 parent a25fda9 commit 08a5bf3

3 files changed

Lines changed: 91 additions & 23 deletions

File tree

‎doc/03-Configuration.md‎

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -41,19 +41,6 @@ config_resource = "icingaweb_db"
4141
module_path = "/usr/share/icingaweb2/modules"
4242
```
4343

44-
### Security Configuration <a id="configuration-general-security"></a>
45-
46-
| Option | Description |
47-
|------------------|---------------------------------------------------------------------------------------------------------------------------------------|
48-
| use\_strict\_csp | **Optional.** Set this to `1` to enable strict [Content Security Policy](20-Advanced-Topics.md#advanced-topics-csp). Defaults to `0`. |
49-
50-
Example:
51-
52-
```
53-
[security]
54-
use_strict_csp = "1"
55-
```
56-
5744
### Logging Configuration <a id="configuration-general-logging"></a>
5845

5946
Option | Description
@@ -87,3 +74,32 @@ Example:
8774
disabled = "1"
8875
default = "high-contrast"
8976
```
77+
78+
## Security Configuration <a id="configuration-security"></a>
79+
80+
Navigate into **Configuration > Application > Security**.
81+
82+
This configuration is stored in the `config.ini` file in `/etc/icingaweb2`.
83+
84+
### Content Security Policy Configuration <a id="configuration-security-csp"></a>
85+
86+
| Option | Description |
87+
|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
88+
| use\_strict\_csp | **Optional.** Set this to `1` to enable strict [Content Security Policy](20-Advanced-Topics.md#advanced-topics-csp). Defaults to `0`. |
89+
| use\_custom\_csp | **Optional.** Set this to `1` to enable the use of the user defined Content Security Policy. Defaults to `0`. |
90+
| custom\_csp | **Optional.** Specifies the user defined Content Security Policy. Overrides the automatically generated one. Only used if `use_custom_csp` is set to `1`. |
91+
| csp\_enable\_modules | **Optional.** Specifies if modules should be included in the generated Content Security Policy. Defaults to `1`. |
92+
| csp\_enable\_dashboards | **Optional.** Specifies if dashboards should be included in the generated Content Security Policy. Defaults to `1`. |
93+
| csp\_enable\_navigation | **Optional.** Specifies if navigation menu items should be included in the generated Content Security Policy. Defaults to `1`. |
94+
95+
Example:
96+
97+
```
98+
[security]
99+
use_strict_csp = "1"
100+
use_custom_csp = "0"
101+
custom_csp = "frame-src https://example.com"
102+
csp_enable_modules = "1"
103+
csp_enable_dashboards = "1"
104+
csp_enable_navigation = "1"
105+
```

‎doc/20-Advanced-Topics.md‎

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -117,24 +117,35 @@ systemctl reload httpd
117117

118118
Elevate your security standards to an even higher level by enabling the [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) for Icinga Web.
119119
Enabling strict CSP can prevent your Icinga Web environment from becoming a potential target of [Cross-Site Scripting (XSS)](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting)
120-
and data injection attacks. After enabling this feature Icinga Web defines all the required CSP headers. Subsequently,
120+
and data injection attacks. After enabling this feature, Icinga Web defines all the required CSP headers. Subsequently,
121121
only content coming from Icinga Web's own origin is accepted, inline JS is prohibited, and inline CSS is accepted only
122122
if it contains the nonce set in the response header.
123123

124124
We decided against enabling this by default as we cannot guarantee that all the modules out there will function correctly.
125125
Therefore, you have to manually enable this policy explicitly and accept the risks that this might break some of
126-
the Icinga Web modules. Icinga Web and all it's components listed below, on the other hand, fully support strict CSP. If
126+
the Icinga Web modules. Icinga Web and all its components listed below, on the other hand, fully support strict CSP. If
127127
that's not the case, please submit an issue on GitHub in the respective repositories.
128128

129-
To enable the strict content security policy navigate to **Configuration > Application** and toggle "Enable strict content security policy",
130-
or set the `use_strict_csp` in the `config.ini`.
129+
To enable the strict content security policy, navigate to **Configuration > Application > Security** and toggle
130+
"Send CSP header", or set `use_strict_csp` in the `config.ini`.
131131

132-
```
133-
vim /etc/icingaweb2/config.ini
132+
Icinga does its best to support user-defined content like navigation items and dashboard dashlets. If that behavior is
133+
not desired, you can disable both by disabling the corresponding feature in the **Security page** at
134+
**Configuration > Application > Security** or by setting `csp_enable_navigation` or `csp_enable_dashboards` in the
135+
`config.ini`. Note that while you can see all navigation items and dashboards, the actual CSP is generated per user
136+
and does not include the full set of directives shown.
134137

135-
[security]
136-
use_strict_csp = "1"
137-
```
138+
If it is necessary to add extra entries to the CSP header, you can do so by using the `CspHook` hook,
139+
read more about it [here](60-Hooks.md#hooks-csp). This is the preferred way to extend the CSP header
140+
because it is an additive and modular approach.
141+
142+
Alternatively you can define your own CSP header by setting the `custom_csp` in the `config.ini` or by configuring the
143+
`Custom CSP` section at **Configuration > Application > Security** which will completely overwrite the generated
144+
CSP header.
145+
Therefore, you are responsible for ensuring that the CSP header is valid, does not contain insecure directives,
146+
is kept up to date with updates or changes to the icingaweb application or its components, and works for every user.
147+
When creating your own CSP header, you can use the placeholder `{style_nonce}` in place of the
148+
automatically generated nonce. This will be replaced with the actual nonce when a user loads icingaweb.
138149

139150
Here is a list of all Icinga Web components that are capable of strict CSP.
140151

@@ -155,6 +166,17 @@ Here is a list of all Icinga Web components that are capable of strict CSP.
155166
| Icinga Web AWS Integration | [v1.1.0](https://github.com/Icinga/icingaweb2-module-aws/releases/tag/v1.1.0) |
156167
| Icinga Web vSphere Integration | [v1.8.0](https://github.com/Icinga/icingaweb2-module-vspheredb/releases/tag/v1.8.0) |
157168

169+
```
170+
vim /etc/icingaweb2/config.ini
171+
172+
[security]
173+
use_strict_csp = "1"
174+
csp_enable_modules = "1"
175+
csp_enable_dashboards = "1"
176+
csp_enable_navigation = "1"
177+
use_custom_csp = "0"
178+
custom_csp = ""
179+
```
158180

159181
## Advanced Authentication Tips <a id="advanced-topics-authentication-tips"></a>
160182

@@ -318,7 +340,7 @@ which may help you already:
318340

319341
If you are automating the installation of Icinga Web 2, you may want to skip the wizard and do things yourself.
320342
These are the steps you'd need to take assuming you are using MySQL/MariaDB. If you are using PostgreSQL please adapt
321-
accordingly. Note you need to have successfully completed the Icinga 2 installation, installed the Icinga Web 2 packages
343+
accordingly. Note you need to have successfully completed the Icinga 2 installation, installed the Icinga Web 2 packages,
322344
and all the other steps described above first.
323345

324346
1. Install PHP dependencies: `php`, `php-intl`, `php-imagick`, `php-gd`, `php-mysql`, `php-curl`, `php-mbstring` used

‎doc/60-Hooks.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,33 @@ class ConfigFormEvents extends ConfigFormEventsHook
4747
}
4848
}
4949
```
50+
51+
## CspHook <a id="hooks-csp"></a>
52+
53+
The `CspHook` allows developers to add custom CSP directives to the Icinga Web 2 frontend.
54+
It provides the method `getCsp()` which should return a `Csp` instance with the directives the module wants to add.
55+
The directives are combined additively with the default directives, icingaweb2 generated ones and other module-defined
56+
directives.
57+
58+
Hook example:
59+
60+
```php
61+
namespace Icinga\Module\Acme\ProvidedHook;
62+
63+
use Icinga\Application\Hook\CspHook;
64+
use ipl\Web\Common\Csp as CspInstance;
65+
66+
class Csp extends CspHook
67+
{
68+
public function getCsp(bool $allUsers): CspInstance
69+
{
70+
$csp = new CspInstance();
71+
$csp->add('img-src', ['cdn.example.com', 'usercontent.example.com']);
72+
$csp->add('style-src', 'cdn.example.com');
73+
74+
// ...
75+
76+
return $csp;
77+
}
78+
}
79+
```

0 commit comments

Comments
 (0)