--- /dev/null
+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:
+
+ <?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.
projects / yaffs-website / blobdiff