www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/security_review/API.txt

   1 For the latest documentation and code examples go to:
   2 https://www.drupal.org/node/2508415
   3
   4 # Security Review API
   5
   6   * Defining a security check
   7     * Identifiers
   8     * Action and messages
   9     * Help page
  10     * Evaluation page (optional)
  11     * Check-specific settings (optional)
  12       * Form generation
  13       * Configuration schema
  14   * Hooks
  15   * Alterable variables
  16   * Drush usage
  17
  18 ## Defining a security check
  19
  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.
  22
  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:
  26     * getNamespace()
  27     * getTitle()
  28     * run()
  29     * help()
  30     * getMessage()
  31
  32   ### Identifiers
  33
  34     There are 5 kinds of identifiers for a given check:
  35       * namespace
  36       * machine namespace
  37       * title
  38       * machine title
  39       * id
  40
  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).
  44
  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.
  50
  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.
  53
  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().
  57
  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
  60     between them.
  61
  62   ### Action and messages
  63
  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.
  67
  68     Instantiating a CheckResult:
  69
  70     CheckResult defines one constructor:
  71     (Check $check, $result, array $findings, $visible = TRUE, $time = NULL)
  72       * $check
  73         The Check that is responsible for the result
  74       * $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
  80       * $findings
  81         An array of findings that can be evaluated. It can be empty.
  82       * $visible
  83         Check results can be hidden from the user by setting $visible to FALSE.
  84       * $time
  85         Timestamp indicating the time when the result was produced. If left null
  86         it will be the current time.
  87
  88     NOTE:
  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).
  92
  93     Human-readable messages for each result integer:
  94
  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.
  98
  99   ### Help page
 100
 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
 104
 105   ### Evaluation page (optional)
 106
 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
 112
 113   ### Check-specific settings (optional)
 114
 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.
 124
 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] .
 128
 129 ## Hooks
 130
 131   ### hook_security_review_checks()
 132
 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.
 136
 137     For example implementations see security_review.api.php and
 138     security_review.module and the examples.
 139
 140   ### hook_security_review_log()
 141
 142     Provides logging functions for various events:
 143     Check skipped / enabled
 144     Check ran
 145     Check gave a NULL result
 146
 147     For example implementations see security_review.api.php and
 148     security_review.module.
 149
 150 ## Alterable variables
 151
 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.
 155   An example:
 156
 157   <?php
 158   // ...
 159   /**
 160    * Implements hook_security_review_unsafe_extensions_alter().
 161    */
 162   function my_module_security_review_unsafe_extensions_alter(array &$variable) {
 163     // Add the .reg file extension to the list of unsafe extensions.
 164     $variable[] = 'reg';
 165   }
 166   ?>
 167
 168   ### security_review_unsafe_tags
 169
 170     The list of HTML tags considered to be unsafe.
 171     See https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet .
 172
 173     Default variable content is at Security::unsafeTags().
 174
 175   ### security_review_unsafe_extensions
 176
 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.
 179
 180     Default variable content is at Security::unsafeExtensions().
 181
 182   ### security_review_file_ignore
 183
 184     The list of relative and absolute paths to ignore when running the File
 185     permissions check.
 186
 187     Default variable content is at FilePermissions::run().
 188
 189   ### security_review_temporary_files
 190
 191     The list of files to check for the Temporary files security check.
 192
 193     Default variable definition is at TemporaryFiles::run().
 194
 195 ## Drush usage
 196
 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.