Add rule suppression annotations

README.md

@@ -71,6 +71,48 @@ You can also get a listing of the current checks being done with the `rules` com
 
     psecio-parse rules
 
+### Managing rules to run
+
+There are several ways to control which rules are run. You can specifically include rules using
+the `--include-rules` option, specifically exclude them with `--exclude-rules`, turn them on and
+off on a case-by-case basis using annotations, and disable annotations using
+`--disable-annotations`.
+
+#### Excluding and Including rules
+
+By default, `psecio-parse scan` includes all available rules in its scan. By using
+`--exclude-rules` and `--include-rules`, the rules included can be reduced.
+
+Any rules specified by `--exclude-rules` are explicity excluded from the scan, regardless of any
+other options selected. These rules cannot be added back to the scan, short of re-running the scan
+with different options. Invalid rules are silently ignored.
+
+If `--include-rules` is provided, only those rules specified can be used. No other rules are
+checked. Note that rules that aren't available (whether they do not exist or `--excluded-rules` is
+used to exclude them) cannot be included. Invalid rules are silently ignored.
+
+#### Annotations
+
+Rules can be enabled and disabled using DocBlock annotations. These are comments in the code being
+scanned that tells *Parse* to specifically enable or disable a rule for the block of code the
+DocBlock applies to.
+
+* `@psecio\parse\disable <rule>`: Tells *Parse* to ignore the given rule for the scope of the
+  DocBlock.
+* `@psecio\parse\enable <rule>`: Tells *Parse* to enable the given rule for the scope of the
+  DocBlock. This can be used to re-enable a particular rule when `@psecio\parse\disable` has been
+  applied to the containing scope.
+
+Note that annotations cannot enable tests that have been omitted via the command line options. If
+a test is disabled at the command line, it is disabled for the entire scan, regardless of any
+annotations.
+
+Comments can be added after `<rule>` following a dobule-slash (`//`) comment separator. It is
+recommended that comments be used to indicate why the rule has been disabled or enabled.
+
+To disable the use of annotations, use the `--disable-annotations` option.
+
+See the `examples` directory for some examples of the ues of annotations for *Parse*.
 
 The Checks
 ----------

composer.json

@@ -16,8 +16,7 @@
         "php": ">=5.4",
         "nikic/php-parser": "~1.0",
         "symfony/console": "~2.5",
-        "symfony/event-dispatcher": "~2.4",
-        "eloquent/blox": "~3.0"
+        "symfony/event-dispatcher": "~2.4"
     },
     "require-dev": {
         "phpunit/phpunit": "4.2.*",

examples/annotations/turnOffRule.php

@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * Turn off the rule for the following function
+ *
+ * @psecio\parse\disable EvalFunction
+ */
+function needsEval()
+{
+    eval('echo "I need eval()\n"');
+}
+
+/**
+ * Previous rule should not affect this one.
+ */
+function evalIsBad()
+{
+    eval('echo "Eval is Evil!"');
+}

examples/annotations/turnOnRule.php

@@ -0,0 +1,35 @@
+<?php
+
+/**
+ * This class turns off BooleanIdentity.
+ *
+ * @psecio\parse\disable BooleanIdentity // This class has lots of brokeness here to be fixed later
+ */
+class testTurnOnRule
+{
+    public function shouldError()
+    {
+        if ($ignoreMe == true) {
+            echo "Check your bools!\n";
+        }
+    }
+
+    /**
+     * @psecio\parse\enable BooleanIdentity  Got the problems solved in this method
+     */
+    public function shouldNotError()
+    {
+        if ($respectMyAuthority == true) {
+            echo "I'm not responsible for your bools.!\n";
+        }
+
+        /** @psecio\parse\disable booleanidentity  But there is a reason for this */
+        if ($butThisCanBeIgnored == false) {
+            echo "But..yeah. Huh.\n";
+        }
+
+        if ($dontIgnoreThis == true) {
+            echo "Now we do the dance of joy!\n";
+        }
+    }
+}

src/CallbackVisitor.php

@@ -5,16 +5,26 @@
 use PhpParser\NodeVisitorAbstract;
 use PhpParser\Node;
 
+use Psecio\Parse\DocComment\DocCommentFactoryInterface;
+
 /**
  * Evaluate rules and call callback on failure
  */
 class CallbackVisitor extends NodeVisitorAbstract
 {
+    const ENABLE_TAG = 'psecio\parse\enable';
+    const DISABLE_TAG = 'psecio\parse\disable';
+
     /**
      * @var RuleCollection Rules to evaluate
      */
     private $ruleCollection;
 
+    /**
+     * @var array List of enabled rules, stored as ruleName => bool
+     */
+    private $enabledRules;
+
     /**
      * @var callable Fail callback
      */
@@ -25,14 +35,35 @@ class CallbackVisitor extends NodeVisitorAbstract
      */
     private $file;
 
+    /**
+     * @var bool  If false, ignore all annotations
+     */
+    private $useAnnotations;
+
+    /**
+     * @var DocCommentFactoryInterface
+     */
+    private $docCommentFactory;
+
     /**
      * Inject rule collection
      *
      * @param RuleCollection $ruleCollection
+     * @param bool           $useAnnotations  If false, ignore all annotations
      */
-    public function __construct(RuleCollection $ruleCollection)
+    public function __construct(RuleCollection $ruleCollection,
+                                DocCommentFactoryInterface $docCommentFactory,
+                                $useAnnotations)
     {
         $this->ruleCollection = $ruleCollection;
+        $this->enabledRules = [];
+
+        foreach ($this->ruleCollection as $rule) {
+            $this->enabledRules[strtolower($rule->getName())] = true;
+        }
+
+        $this->useAnnotations = $useAnnotations;
+        $this->docCommentFactory = $docCommentFactory;
     }
 
     /**
@@ -64,10 +95,65 @@ public function setFile(File $file)
      */
     public function enterNode(Node $node)
     {
+        if ($this->useAnnotations) {
+            $this->updateRuleFilters($node);
+        }
+
         foreach ($this->ruleCollection as $rule) {
-            if (!$rule->isValid($node)) {
-                call_user_func($this->callback, $rule, $node, $this->file);
-            }
+            $this->evaluateRule($node, $rule);
+        }
+    }
+
+    protected function evaluateRule($node, $rule)
+    {
+        if (!$this->enabledRules[strtolower($rule->getName())]) {
+            return;
+        }
+
+        if (!$rule->isValid($node)) {
+            call_user_func($this->callback, $rule, $node, $this->file);
+        }
+    }
+
+    public function leaveNode(Node $node)
+    {
+        if (!$node->hasAttribute('oldEnabledRules')) {
+            return;
+        }
+
+        // Restore rules as they were before this node
+        $this->enabledRules = $node->getAttribute('oldEnabledRules');
+    }
+
+    private function updateRuleFilters($node)
+    {
+        $docBlock = $node->getDocComment();
+        if (empty($docBlock)) {
+            return;
+        }
+
+        $node->setAttribute('oldEnabledRules', $this->enabledRules);
+        $this->enabledRules = $this->evaluateDocBlock($docBlock, $this->enabledRules);
+    }
+
+    private function evaluateDocBlock($docBlock, $rules)
+    {
+        $comment = $this->docCommentFactory->createDocComment($docBlock);
+
+        $this->checkTags($comment, $rules, self::ENABLE_TAG, true);
+        $this->checkTags($comment, $rules, self::DISABLE_TAG, false);
+
+        return $rules;
+    }
+
+    private function checkTags(DocComment\DocCommentInterface $comment, &$rules, $tag, $value)
+    {
+        $tags = $comment->getIMatchingTags($tag);
+
+        foreach ($tags as $rule) {
+            // Get the first word from content. This allows you to add comments to rules.
+            $ruleName = trim(strtolower(strtok($rule, '//')));
+            $rules[$ruleName] = $value;
         }
     }
 }

src/Command/ScanCommand.php

@@ -23,6 +23,7 @@
 use Psecio\Parse\Scanner;
 use Psecio\Parse\CallbackVisitor;
 use Psecio\Parse\FileIterator;
+use Psecio\Parse\DocComment\DocCommentFactory;
 use RuntimeException;
 
 /**
@@ -45,39 +46,45 @@ protected function configure()
             )
             ->addOption(
                 'format',
-                null,
+                'f',
                 InputOption::VALUE_REQUIRED,
                 'Output format (progress, dots or xml)',
                 'progress'
             )
             ->addOption(
                 'ignore-paths',
-                null,
+                'i',
                 InputOption::VALUE_REQUIRED,
                 'Comma-separated list of paths to ignore',
                 ''
             )
             ->addOption(
                 'extensions',
-                null,
+                'x',
                 InputOption::VALUE_REQUIRED,
                 'Comma-separated list of file extensions to parse',
                 'php,phps,phtml,php5'
             )
             ->addOption(
                 'whitelist-rules',
-                null,
+                'w',
                 InputOption::VALUE_REQUIRED,
                 'Comma-separated list of rules to use',
                 ''
             )
             ->addOption(
                 'blacklist-rules',
-                null,
+                'b',
                 InputOption::VALUE_REQUIRED,
                 'Comma-separated list of rules to skip',
                 ''
             )
+            ->addOption(
+                'disable-annotations',
+                'd',
+                InputOption::VALUE_NONE,
+                'Skip all annotation-based rule toggles.'
+            )
             ->setHelp(
                 "Scan paths for possible security issues:\n\n  <info>psecio-parse %command.name% /path/to/src</info>\n"
             );
@@ -151,7 +158,16 @@ function (RuleInterface $rule) {
 
         $dispatcher->dispatch(Events::DEBUG, new MessageEvent("Using ruleset $ruleNames"));
 
-        $scanner = new Scanner($dispatcher, new CallbackVisitor($ruleCollection));
+        $docCommentFactory = new DocCommentFactory();
+
+        $scanner = new Scanner(
+            $dispatcher,
+            new CallbackVisitor(
+                $ruleCollection,
+                $docCommentFactory,
+                !$input->getOption('disable-annotations')
+            )
+        );
         $scanner->scan($fileIterator);
 
         return $exitCode->getExitCode();