API.txt in Security Review 8

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:

  
  // ...
  /**
   * 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.