-
Notifications
You must be signed in to change notification settings - Fork 4
/
API.txt
198 lines (148 loc) · 7.13 KB
/
API.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
For the latest documentation and code examples go to:
https://www.drupal.org/node/2508415
# Security Review API
* Defining a security check
* Identifiers
* Action and messages
* Help page
* Evaluation page (optional)
* Check-specific settings (optional)
* Form generation
* Configuration schema
* Hooks
* Alterable variables
* Drush usage
## Defining a security check
This part of the documentation lets the developer understand the behavior of
the module. If anything's unclear it is recommended to look at the examples.
To define a security check for Security Review, one has to create a class that
extends Drupal\security_review\Check.
The functions that must be overridden are the following:
* getNamespace()
* getTitle()
* run()
* help()
* getMessage()
### Identifiers
There are 5 kinds of identifiers for a given check:
* namespace
* machine namespace
* title
* machine title
* id
The 'namespace' must be manually set for each check by overriding the
getNamespace() method. This is the human-readable namespace of the check
(usually the module's name).
The 'machine namespace' is the version of namespace that is used internally.
If getMachineNamespace() isn't overridden, then it is produced from the
human-readable namespace by removing any non-alphanumeric characters and
replacing spaces with underscores. When overriding getMachineNamespace()
this rule must be followed.
The 'title' must be manually set for each check by overriding the getTitle()
method. This is the human-readable title of the check.
The 'machine title' has the same relationship to 'title' as 'machine
namespace' has to 'namespace'. The machine title should be unique to the
namespace. This might only be achievable by overriding getMachineTitle().
The 'id' is only used internally and cannot be overridden. It's constructed
by taking the 'machine namespace' and 'machine title' and putting a hyphen
between them.
### Action and messages
The part where the actual security check happens is the run() method. This
method must be overridden, and should always return an instance of
Drupal\security_review\CheckResult.
Instantiating a CheckResult:
CheckResult defines one constructor:
(Check $check, $result, array $findings, $time = NULL)
* $check
The Check that is responsible for the result
* $result
An integer that defines the outcome of the check:
* CheckResult::SUCCESS - for a successful check
* CheckResult::FAIL - for a failed check
* CheckResult::WARN - for a check that only raised a warning
* CheckResult::INFO - general result for providing information
* CheckResult::HIDE - for a check result that should not be shown
* Do NOT use the SKIPPED constant! It's reserved for internal usage.
* $findings
An array of findings that can be evaluated. It can be empty.
* $time
Timestamp indicating the time when the result was produced. If left null
it will be the current time.
NOTE:
It's easier to instantiate a result with Check's createResult() method. It
has the same parameters as the constructor for CheckResult, except the
$check is left out (set to $this).
Human-readable messages for each result integer:
Must be defined by overriding the getMessage() method. The implementation is
usually a switch-case. For more details take a look at Security Review's own
Check implementations.
### Help page
Every Check can have its own help page by overriding the help() method. This
should return a render array.
See https://www.drupal.org/developing/api/8/render/arrays
### Evaluation page (optional)
The evaluation page is for providing an evaluation of a CheckResult produced
by the Check. Overriding this is optional, the default implementation
returns an empty array. If one chooses to override evaluate(), the function
must return a render array.
See https://www.drupal.org/developing/api/8/render/arrays
### Check-specific settings (optional)
If the Check requires storage for settings, it can be accessed via
$this->settings(). This method returns a
Drupal\security_review\CheckSettingsInterface. It has get() and set()
methods for accessing the stored configuration, and buildForm(),
submitForm(), validateForm() for form building. By default Check's
implementation contains a Drupal\security_review\CheckSettings, which stores
the values in the Configuration system, and does nothing in its form
building methods. Usually it's enough to extend this class if the Check
needs separate settings on the Security Review settings page.
When using check-specific settings it's recommended to define a
configuration schema to store the values in their correct types. The schema
to declare is called security_review.check_settings.[id of check] .
## Hooks
### hook_security_review_checks()
To let Security Review know of the checks defined in the module it has to
implement hook_security_review_checks(). This hook is fairly simple. It has
to return an array of check instances.
For example implementations see security_review.api.php and
security_review.module and the examples.
### hook_security_review_log()
Provides logging functions for various events:
Check skipped / enabled
Check ran
Check gave a NULL result
For example implementations see security_review.api.php and
security_review.module.
## Alterable variables
To understand what alterable variables are, take a look at
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Extension!ModuleHandler.php/function/ModuleHandler%3A%3Aalter/8
To modify an alterable variable you have to implement hook_[TYPE]_alter.
An example:
<?php
// ...
/**
* Implements hook_security_review_unsafe_extensions_alter().
*/
function my_module_security_review_unsafe_extensions_alter(array &$variable) {
// Add the .reg file extension to the list of unsafe extensions.
$variable[] = 'reg';
}
?>
### security_review_unsafe_tags
The list of HTML tags considered to be unsafe.
See https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet .
Default variable content is at Security::unsafeTags().
### security_review_unsafe_extensions
The list of file extensions considered to be unsafe for upload. Untrusted
users should not be allowed to upload files of these extensions.
Default variable content is at Security::unsafeExtensions().
### security_review_file_ignore
The list of relative and absolute paths to ignore when running the File
permissions check.
Default variable content is at FilePermissions::run().
### security_review_temporary_files
The list of files to check for the Temporary files security check.
Default variable definition is at TemporaryFiles::run().
## Drush usage
Run the checklist via Drush with the "drush security-review" command.
Consult the Drush help on the security-review command for more information.