feat: add detection reasons to findings output

Author: Saharsh1123

detectors/find_secrets.py

@@ -35,7 +35,7 @@ def detect_ast_secrets(code):
             vulnerabilities = apply_rules(var_name, val)
 
             if vulnerabilities:
-                for pattern_name, severity, value in vulnerabilities:
-                    findings.append((line_number, pattern_name, severity, value))
+                for pattern_name, severity, value, reason in vulnerabilities:
+                    findings.append((line_number, pattern_name, severity, value, reason))
 
     return findings

detectors/rule_engine.py

@@ -22,13 +22,13 @@ def apply_rules(var_name, val):
         # Match structured secret values, such as AWS access keys
         if "value_pattern" in data:
             if data["value_pattern"].fullmatch(val):
-                findings.append((rule, data["severity"], val))
+                findings.append((rule, data["severity"], val, data["reason"]))
 
         # Match suspicious variable names and enforce minimum value length
         if "var_patterns" in data:
             for pattern in data["var_patterns"]:
                 match = pattern.search(var_name)
                 if match and len(val) >= data["min_length"]:
-                    findings.append((rule, data["severity"], val))
+                    findings.append((rule, data["severity"], val, data["reason"]))
 
     return findings or None

detectors/rules.py

@@ -9,6 +9,7 @@
     "AWS Access Key": {
         "value_pattern": re.compile(r"(AKIA[0-9A-Z]{16})"),
         "severity": "HIGH",
+        "reason": "value matched AKIA-prefixed AWS access key pattern",
     },
     "Password": {
         "var_patterns": [
@@ -18,6 +19,7 @@
         ],
         "min_length": 4,
         "severity": "HIGH",
+        "reason": "variable name matched password/pwd/passwd pattern and value met minimum length",
     },
     "API Key": {
         "var_patterns": [
@@ -26,17 +28,20 @@
         ],
         "min_length": 4,
         "severity": "HIGH",
+        "reason": "variable name matched api_key/apikey pattern and value met minimum length",
     },
     "Token": {
         "var_patterns": [re.compile(r"token", re.IGNORECASE)],
         "min_length": 4,
         "severity": "MEDIUM",
+        "reason": "variable name matched token pattern and value met minimum length",
     },
     "Secret": {
         "var_patterns": [
             re.compile(r"secret", re.IGNORECASE),
         ],
         "min_length": 4,
         "severity": "MEDIUM",
+        "reason": "variable name matched secret pattern and value met minimum length",
     },
 }

output.py

@@ -18,9 +18,9 @@ def filter_results(results, chosen_severity):
             Filtered findings matching the selected severity.
     """
     filtered_findings = []
-    for line_number, file, rule_name, severity, value in results:
+    for line_number, file, rule_name, severity, value, reason in results:
         if severity == chosen_severity or chosen_severity is None:
-            filtered_findings.append((line_number, file, rule_name, severity, value))
+            filtered_findings.append((line_number, file, rule_name, severity, value, reason))
     return filtered_findings
 
 
@@ -36,13 +36,14 @@ def output_json(filtered_findings):
         None
     """
     json_results = []
-    for line_number, file, rule_name, severity, value in filtered_findings:
+    for line_number, file, rule_name, severity, value, reason in filtered_findings:
         finding = {
             "line": line_number,
             "file": str(file),
             "rule": rule_name,
             "severity": severity,
             "value": value,
+            "reason": reason,
         }
         json_results.append(finding)
     print(json.dumps(json_results, indent=2))
@@ -76,7 +77,8 @@ def output(filtered_findings, use_json, files):
     else:
         print("\n--- Findings ---\n")
 
-        for line_number, file, rule_name, severity, value in filtered_findings:
+        for line_number, file, rule_name, severity, value, reason in filtered_findings:
             print(f"[{severity}] {file}:{line_number} {rule_name} → {value}")
+            print(f"       Reason: {reason}\n")
 
         print(f"\nTotal findings: {len(filtered_findings)}")

scanner.py

@@ -72,8 +72,8 @@ def scan(files):
             content = f.read()
 
             ast_results = detect_ast_secrets(content)
-            for line_number, rule_name, severity, value in ast_results:
-                findings.append((line_number, file, rule_name, severity, value))
+            for line_number, rule_name, severity, value, reason in ast_results:
+                findings.append((line_number, file, rule_name, severity, value, reason))
 
     return findings