Merge pull request #424 from owasp-noir/add-ps-documents

Add passive scan documents
owasp-noir · Oct 1, 2024 · fba30bd · fba30bd
2 parents c71196f + adb60e0
commit fba30bd
Show file tree

Hide file tree

Showing 12 changed files with 245 additions and 83 deletions.
diff --git a/README.md b/README.md
@@ -57,43 +57,44 @@ noir -b . -u https://testapp.internal.domains -f json -T
 ```
 
 ```json
-[
-  {
-    "url": "https://testapp.internal.domains/query",
-    "method": "POST",
-    "params": [
-      {
-        "name": "my_auth",
-        "value": "",
-        "param_type": "cookie",
-        "tags": []
-      },
-      {
-        "name": "query",
-        "value": "",
-        "param_type": "form",
-        "tags": [
+{
+  "endpoints": [
+    {
+      "url": "https://testapp.internal.domains/query",
+      "method": "POST",
+      "params": [
+        {
+          "name": "my_auth",
+          "value": "",
+          "param_type": "cookie",
+          "tags": []
+        },
+        {
+          "name": "query",
+          "value": "",
+          "param_type": "form",
+          "tags": [
+            {
+              "name": "sqli",
+              "description": "This parameter may be vulnerable to SQL Injection attacks.",
+              "tagger": "Hunt"
+            }
+          ]
+        }
+      ],
+      "details": {
+        "code_paths": [
           {
-            "name": "sqli",
-            "description": "This parameter may be vulnerable to SQL Injection attacks.",
-            "tagger": "Hunt"
+            "path": "spec/functional_test/fixtures/crystal_kemal/src/testapp.cr",
+            "line": 8
           }
         ]
-      }
-    ],
-    "details": {
-      "code_paths": [
-        {
-          "path": "testapp/src/testapp.cr",
-          "line": 8
-        }
-      ]
-    },
-    "protocol": "http",
-    "tags": []
-  }
-  ...
-]
+      },
+      "protocol": "http",
+      "tags": []
+    }
+  ]
+}
 ```
 
 For more details, please visit our [documentation](https://owasp-noir.github.io/noir/) page.

diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -5,24 +5,24 @@ GEM
       public_suffix (>= 2.0.2, < 7.0)
     bigdecimal (3.1.8)
     colorator (1.1.0)
-    concurrent-ruby (1.3.3)
+    concurrent-ruby (1.3.4)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
     ffi (1.17.0-arm64-darwin)
     ffi (1.17.0-x86_64-linux-gnu)
     forwardable-extended (2.6.0)
-    google-protobuf (4.27.5-arm64-darwin)
+    google-protobuf (4.28.2-arm64-darwin)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.27.5-x86_64-linux)
+    google-protobuf (4.28.2-x86_64-linux)
       bigdecimal
       rake (>= 13)
     http_parser.rb (0.8.0)
-    i18n (1.14.5)
+    i18n (1.14.6)
       concurrent-ruby (~> 1.0)
-    jekyll (4.3.3)
+    jekyll (4.3.4)
       addressable (~> 2.4)
       colorator (~> 1.0)
       em-websocket (~> 0.5)
@@ -42,13 +42,13 @@ GEM
       jekyll (>= 3.7, < 5.0)
     jekyll-sass-converter (3.0.0)
       sass-embedded (~> 1.54)
-    jekyll-securitytxt (1.0.1)
+    jekyll-securitytxt (1.0.2)
       jekyll
     jekyll-seo-tag (2.8.0)
       jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    just-the-docs (0.8.2)
+    just-the-docs (0.10.0)
       jekyll (>= 3.8.5)
       jekyll-include-cache
       jekyll-seo-tag (>= 2.0)
@@ -64,24 +64,22 @@ GEM
     mercenary (0.4.0)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (6.0.0)
+    public_suffix (6.0.1)
     rake (13.2.1)
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rexml (3.3.6)
-      strscan
-    rouge (4.2.1)
+    rexml (3.3.8)
+    rouge (4.4.0)
     safe_yaml (1.0.5)
-    sass-embedded (1.77.1-arm64-darwin)
-      google-protobuf (>= 3.25, < 5.0)
-    sass-embedded (1.77.1-x86_64-linux-gnu)
-      google-protobuf (>= 3.25, < 5.0)
-    strscan (3.1.0)
+    sass-embedded (1.79.4-arm64-darwin)
+      google-protobuf (~> 4.27)
+    sass-embedded (1.79.4-x86_64-linux-gnu)
+      google-protobuf (~> 4.27)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
-    unicode-display_width (2.5.0)
-    webrick (1.8.1)
+    unicode-display_width (2.6.0)
+    webrick (1.8.2)
 
 PLATFORMS
   arm64-darwin

diff --git a/docs/_advanced/diff.md b/docs/_advanced/diff.md
@@ -1,7 +1,7 @@
 ---
 title: Diff Mode
 has_children: false
-nav_order: 4
+nav_order: 5
 layout: page
 ---
 

diff --git a/docs/_advanced/passive_scan.md b/docs/_advanced/passive_scan.md
@@ -0,0 +1,47 @@
+---
+title: Passive Scan
+has_children: true
+nav_order: 4
+layout: page
+---
+
+A Passive Scan is a feature where additional actions are performed by the Detector to identify security issues according to scan rules. This functionality typically includes:
+
+* Regular Expression Matching: It uses regular expressions to match patterns that could indicate security vulnerabilities.
+* String Matching: Besides regex, it looks for specific strings within the code that could be indicative of security concerns.
+* Default Rule Set: Comes with a predefined set of rules to check against common security issues.
+
+```bash
+noir -b <BASE_PATH> -P
+
+# You can check the format list with the -h flag.
+#  PASSIVE SCAN:
+#    -P, --passive-scan               Perform a passive scan for security issues using rules from the specified path
+#    --passive-scan-path PATH         Specify the path for the rules used in the passive security scan
+```
+
+Usage Example:
+
+When you run a command like:
+
+```bash
+noir -b ./your_app -P
+```
+
+The passive scan might produce results like:
+
+```
+★ Passive Results:
+[critical][hahwul-test][secret] use x-api-key
+  ├── extract:   env.request.headers["x-api-key"].as(String)
+  └── file: ./spec/functional_test/fixtures/crystal_kemal/src/testapp.cr:4
+```
+
+Explanation of Output:
+
+* Label: `[critical][hahwul-test][secret]` - This line indicates the severity, test context, and type of issue found. Here, it's critical, related to a test named hahwul-test, and concerns a secret.
+* Extract: This shows where or how the sensitive information is being accessed or used. In this case, it's extracting an x-api-key from the request headers.
+* File: Indicates the location of the potential security issue within the codebase, pointing to the exact file and line number where the issue was detected.
+
+This output helps developers immediately identify where and what kind of security issues exist in their code, focusing on passive analysis without actively exploiting the vulnerabilities.
+'
diff --git a/docs/_advanced/passive_scan/default_rules.md b/docs/_advanced/passive_scan/default_rules.md
@@ -0,0 +1,19 @@
+---
+title: Default Rules
+parent: Passive Scan
+has_children: false
+nav_order: 2
+layout: page
+---
+
+The default rules are stored in the following paths based on your operating system:
+
+| OS | Path |
+|---|---|
+| MacOS: | `~/.config/noir/passive_rules/` |
+| Linux: | `~/.config/noir/passive_rules/` |
+| Windows: | `%APPDATA%\noir\passive_rules\` |
+
+When using the `-P` (`--passive-scan`) flag, Noir references the rules stored in these paths. These rules are managed by the Noir team, ensuring they are up-to-date and effective.
+
+However, if you wish to add your own custom rules, you can place them in the respective directory for your operating system. This allows you to extend the functionality of the passive scan to meet your specific needs.
diff --git a/docs/_advanced/passive_scan/rule.md b/docs/_advanced/passive_scan/rule.md
@@ -0,0 +1,72 @@
+---
+title: Passive Scan Rule
+parent: Passive Scan
+has_children: false
+nav_order: 1
+layout: page
+---
+
+```yaml
+id: rule-id
+info:
+  name: "The name of the rule"
+  author: 
+    - "List of authors"
+    - "Another author"
+  severity: "The severity level of the rule (e.g., critical, high, medium, low)"
+  description: "A brief description of the rule"
+  reference:
+    - "URLs or references related to the rule"
+
+matchers-condition: "The condition to apply between matchers (and/or)"
+matchers:
+  - type: "The type of matcher (e.g., word, regex)"
+    patterns:
+      - "Patterns to match"
+    condition: "The condition to apply within the matcher (and/or)"
+
+  - type: "The type of matcher (e.g., word, regex)"
+    patterns:
+      - "Patterns to match"
+      - "Another pattern"
+    condition: "The condition to apply within the matcher (and/or)"
+
+category: "The category of the rule (e.g., secret, vulnerability)"
+techs:
+  - "Technologies or frameworks the rule applies to"
+  - "Another technology"
+```
+
+### Example Rule: Detecting PRIVATE_KEY
+
+```yaml
+id: detect-private-key
+info:
+  name: "Detect PRIVATE_KEY"
+  author: 
+    - "security-team"
+  severity: critical
+  description: "Detects the presence of PRIVATE_KEY in the code"
+  reference:
+    - "https://example.com/security-guidelines"
+
+matchers-condition: or
+matchers:
+  - type: word
+    patterns:
+      - "PRIVATE_KEY"
+      - "-----BEGIN PRIVATE KEY-----"
+    condition: or
+
+  - type: regex
+    patterns:
+      - "PRIVATE_KEY\\s*=\\s*['\"]?[^'\"]+['\"]?"
+      - "-----BEGIN PRIVATE KEY-----[\\s\\S]*?-----END PRIVATE KEY-----"
+    condition: or
+
+category: secret
+techs:
+  - '*'
+```
+
+![](../../../images/advanced/passive_private_key.png)
diff --git a/docs/_get_started/output/json.md b/docs/_get_started/output/json.md
@@ -13,38 +13,42 @@ noir -b . -f json --no-log
 
 ```json
 {
-    "url": "https://testapp.internal.domains/query",
-    "method": "POST",
-    "params": [
-      {
-        "name": "my_auth",
-        "value": "",
-        "param_type": "cookie",
-        "tags": []
-      },
-      {
-        "name": "query",
-        "value": "",
-        "param_type": "form",
-        "tags": [
+  "endpoints": [
+    {
+      "url": "https://testapp.internal.domains/query",
+      "method": "POST",
+      "params": [
+        {
+          "name": "my_auth",
+          "value": "",
+          "param_type": "cookie",
+          "tags": []
+        },
+        {
+          "name": "query",
+          "value": "",
+          "param_type": "form",
+          "tags": [
+            {
+              "name": "sqli",
+              "description": "This parameter may be vulnerable to SQL Injection attacks.",
+              "tagger": "Hunt"
+            }
+          ]
+        }
+      ],
+      "details": {
+        "code_paths": [
           {
-            "name": "sqli",
-            "description": "This parameter may be vulnerable to SQL Injection attacks.",
-            "tagger": "Hunt"
+            "path": "spec/functional_test/fixtures/crystal_kemal/src/testapp.cr",
+            "line": 8
           }
         ]
-      }
-    ],
-    "details": {
-      "code_paths": [
-        {
-          "path": "spec/functional_test/fixtures/crystal_kemal/src/testapp.cr",
-          "line": 8
-        }
-      ]
-    },
-    "protocol": "http",
-    "tags": []
+      },
+      "protocol": "http",
+      "tags": []
+    }
+  ]
 }
 ```
 

diff --git a/docs/_get_started/output/yaml.md b/docs/_get_started/output/yaml.md
@@ -11,6 +11,7 @@ noir -b . -f yaml --no-log
 ```
 
 ```yaml
+endpoints:
 - url: /
   method: GET
   params:

diff --git a/docs/images/advanced/passive_private_key.png b/docs/images/advanced/passive_private_key.png