Sample Rule

The following rule sample demonstrates the DevSkim rule format.

Rule Description

The rule detects unsafe content being generated as an output in PHP, such as form input variables that are displayed on the web page without proper HTML encoding. For example, echo($_POST["name"]) is considered unsafe because the user-controlled variable name can contain malicious HTML/JavaScript content. Such content can be abused in Cross-Site Scripting Attacks (XSS).

Notice that the rule conditions prevent it from being triggered when a variable is properly encoded. For example, echo(htmlentities($_POST["name"])) is considered safe, because the function htmlentities will safely escape all HTML content in the variable.

The rule contains fix-it records, such as using the htmlentities function to properly encode the variable before displaying it on the web page.

Rule Sample

{
  "name": "XSS: Do not echo unencoded GET/POST/COOKIE values",
  "id": "DS163877",
  "description": "When using $_GET/POST/COOKIE values via echo, failure to  encode the values will lead to Cross Site Scription (XSS), where a malicious party can inject script into the webpage.",
  "recommendation": "HTML Entity Encode (for content going into HTML) or URL Encode (for content going into JavaScript variables) the data",
  "applies_to": [
      "php"
  ],
  "tags": [
      "Implementation.PHP"
  ],
  "severity": "moderate",
  "_comment": "",
  "rule_info": "DS163877.md",
  "patterns": [
      {
          "pattern": "\\becho.*(\\$_(POST|GET|REQUEST|COOKIE)\\[.*\\]).*;",
          "type": "regex",
          "scopes": [
              "code"
          ],
          "_comment": ""
      }
  ],
  "conditions" : [
      {
          "pattern" : 
          {
              "pattern": "\\b(htmlentities|htmlspecialchars|rawurlencode|urlencode)\\s*\\(.*(\\$_(POST|GET|REQUEST|COOKIE)\\[.*\\]).*\\)",
              "type": "regex",
              "scopes": [
                  "code"
              ],
              "_comment": ""
          },
          "search_in":"finding-only",
          "negate_finding": true,
          "_comment": "" 
      }          
  ],
  "fix_its": [
      {
          "name": "HTML Entity encode the data",
          "type": "regex-replace",
          "_comment": "",
          "replacement": "htmlentities($1)",
          "pattern": {
              "pattern": "(\\$_(POST|GET|REQUEST|COOKIE)\\[.*\\])",
              "type": "regex",
              "scopes": [
                  "code"
              ],
              "_comment": ""
          }
      },
      {
          "name": "URL encode the data",
          "type": "regex-replace",
          "_comment": "",
          "replacement": "rawurlencode($1)",
          "pattern": {
              "pattern": "(\\$_(POST|GET|REQUEST|COOKIE)\\[.*\\])",
              "type": "regex",
              "scopes": [
                  "code"
              ],
              "_comment": ""
          }
      }
  ]
}

Rule Fields

This list describes the purpose of the each of the top level fields in the sample rule above.

Name

A short string representing a name for the rule

ID

A semi-unique string that serves as an identifier for the rule. Also used to tie rules with DevSkim guidance

Description

A longer description of the purpose of the rule

Recommendation

A user facing recommendation for actions that may help to fix issues identified by the rule

Applies To

A list of language names which the rule should apply to. If empty, the rule will apply to all languages

Tags

A list of tags/categories the rule falls into

Severity

An enum representing the seriousness of the issue detected

Comment

A field used for rule authors to add comments to the rule file

Rule Info

The name of the guidance markdown file in the DevSkim repository (if any) related to the rule

Patterns

A list of patterns defining when the rule should apply

Conditions

A list of conditions on the patterns to restrict when the rule will apply

Fix Its

A list of potential fixes that can be applied by DevSkim to fix the issue identified by the rule