1 For the latest documentation and code examples go to:
2 https://www.drupal.org/node/2508415
6 * Defining a security check
10 * Evaluation page (optional)
11 * Check-specific settings (optional)
13 * Configuration schema
18 ## Defining a security check
20 This part of the documentation lets the developer understand the behavior of
21 the module. If anything's unclear it is recommended to look at the examples.
23 To define a security check for Security Review, one has to create a class that
24 extends Drupal\security_review\Check.
25 The functions that must be overridden are the following:
34 There are 5 kinds of identifiers for a given check:
41 The 'namespace' must be manually set for each check by overriding the
42 getNamespace() method. This is the human-readable namespace of the check
43 (usually the module's name).
45 The 'machine namespace' is the version of namespace that is used internally.
46 If getMachineNamespace() isn't overridden, then it is produced from the
47 human-readable namespace by removing any non-alphanumeric characters and
48 replacing spaces with underscores. When overriding getMachineNamespace()
49 this rule must be followed.
51 The 'title' must be manually set for each check by overriding the getTitle()
52 method. This is the human-readable title of the check.
54 The 'machine title' has the same relationship to 'title' as 'machine
55 namespace' has to 'namespace'. The machine title should be unique to the
56 namespace. This might only be achievable by overriding getMachineTitle().
58 The 'id' is only used internally and cannot be overridden. It's constructed
59 by taking the 'machine namespace' and 'machine title' and putting a hyphen
62 ### Action and messages
64 The part where the actual security check happens is the run() method. This
65 method must be overridden, and should always return an instance of
66 Drupal\security_review\CheckResult.
68 Instantiating a CheckResult:
70 CheckResult defines one constructor:
71 (Check $check, $result, array $findings, $visible = TRUE, $time = NULL)
73 The Check that is responsible for the result
75 An integer that defines the outcome of the check:
76 * CheckResult::SUCCESS - for a successful check
77 * CheckResult::FAIL - for a failed check
78 * CheckResult::WARN - for a check that only raised a warning
79 * CheckResult::INFO - general result for providing information
81 An array of findings that can be evaluated. It can be empty.
83 Check results can be hidden from the user by setting $visible to FALSE.
85 Timestamp indicating the time when the result was produced. If left null
86 it will be the current time.
89 It's easier to instantiate a result with Check's createResult() method. It
90 has the same parameters as the constructor for CheckResult, except the
91 $check is left out (set to $this).
93 Human-readable messages for each result integer:
95 Must be defined by overriding the getMessage() method. The implementation is
96 usually a switch-case. For more details take a look at Security Review's own
97 Check implementations.
101 Every Check can have its own help page by overriding the help() method. This
102 should return a render array.
103 See https://www.drupal.org/developing/api/8/render/arrays
105 ### Evaluation page (optional)
107 The evaluation page is for providing an evaluation of a CheckResult produced
108 by the Check. Overriding this is optional, the default implementation
109 returns an empty array. If one chooses to override evaluate(), the function
110 must return a render array.
111 See https://www.drupal.org/developing/api/8/render/arrays
113 ### Check-specific settings (optional)
115 If the Check requires storage for settings, it can be accessed via
116 $this->settings(). This method returns a
117 Drupal\security_review\CheckSettingsInterface. It has get() and set()
118 methods for accessing the stored configuration, and buildForm(),
119 submitForm(), validateForm() for form building. By default Check's
120 implementation contains a Drupal\security_review\CheckSettings, which stores
121 the values in the Configuration system, and does nothing in its form
122 building methods. Usually it's enough to extend this class if the Check
123 needs separate settings on the Security Review settings page.
125 When using check-specific settings it's recommended to define a
126 configuration schema to store the values in their correct types. The schema
127 to declare is called security_review.check_settings.[id of check] .
131 ### hook_security_review_checks()
133 To let Security Review know of the checks defined in the module it has to
134 implement hook_security_review_checks(). This hook is fairly simple. It has
135 to return an array of check instances.
137 For example implementations see security_review.api.php and
138 security_review.module and the examples.
140 ### hook_security_review_log()
142 Provides logging functions for various events:
143 Check skipped / enabled
145 Check gave a NULL result
147 For example implementations see security_review.api.php and
148 security_review.module.
150 ## Alterable variables
152 To understand what alterable variables are, take a look at
153 https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Extension!ModuleHandler.php/function/ModuleHandler%3A%3Aalter/8
154 To modify an alterable variable you have to implement hook_[TYPE]_alter.
160 * Implements hook_security_review_unsafe_extensions_alter().
162 function my_module_security_review_unsafe_extensions_alter(array &$variable) {
163 // Add the .reg file extension to the list of unsafe extensions.
168 ### security_review_unsafe_tags
170 The list of HTML tags considered to be unsafe.
171 See https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet .
173 Default variable content is at Security::unsafeTags().
175 ### security_review_unsafe_extensions
177 The list of file extensions considered to be unsafe for upload. Untrusted
178 users should not be allowed to upload files of these extensions.
180 Default variable content is at Security::unsafeExtensions().
182 ### security_review_file_ignore
184 The list of relative and absolute paths to ignore when running the File
187 Default variable content is at FilePermissions::run().
189 ### security_review_temporary_files
191 The list of files to check for the Temporary files security check.
193 Default variable definition is at TemporaryFiles::run().
197 Run the checklist via Drush with the "drush security-review" command.
198 Consult the Drush help on the security-review command for more information.