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=627e264e81e8d3cc8b87414fe65f96ad4c0d417c;hp=0000000000000000000000000000000000000000;hb=ba1b5c55c66590c41ccc9844d3e62391b0399abb;hpb=93ef30d42f68e55d11d97312531118bbcd4cf318

diff --git a/web/modules/contrib/security_review/API.txt b/web/modules/contrib/security_review/API.txt
new file mode 100644
index 000000000..627e264e8
--- /dev/null
+++ b/web/modules/contrib/security_review/API.txt
@@ -0,0 +1,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, $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.