X-Git-Url: http://www.aleph1.co.uk/gitweb/?p=yaffs-website;a=blobdiff_plain;f=web%2Fmodules%2Fcontrib%2Fsecurity_review%2FAPI.txt;fp=web%2Fmodules%2Fcontrib%2Fsecurity_review%2FAPI.txt;h=0000000000000000000000000000000000000000;hp=627e264e81e8d3cc8b87414fe65f96ad4c0d417c;hb=419f97be044f1aebd0713921ee604841127e9e84;hpb=052617e40b525f8b817d84c29b1c04951f427069 diff --git a/web/modules/contrib/security_review/API.txt b/web/modules/contrib/security_review/API.txt deleted file mode 100644 index 627e264e8..000000000 --- a/web/modules/contrib/security_review/API.txt +++ /dev/null @@ -1,198 +0,0 @@ -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, $visible = TRUE, $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 - * $findings - An array of findings that can be evaluated. It can be empty. - * $visible - Check results can be hidden from the user by setting $visible to FALSE. - * $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: - - - - ### 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.