shield_ast 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b38d31d7f4411ba2d4de694915019f9059cf19bab67079473c4597066d5e8269
-  data.tar.gz: 60d6255349f02a11a5c85adf5ec10b9de6019b7c9d9694d15f3101ffef838301
+  metadata.gz: e1d0d992a06ba8323c653c415034bf1a8675927313eed774e0df9604d68ac0d4
+  data.tar.gz: dde5863c280c005ff476e9155dd079ef61718ada91d858fdce39139d9d921c67
 SHA512:
-  metadata.gz: afc99954084847d8c6d9e9d1348638169039d2bc08a0370d7f5d86e50ad2a6d146f0724423151f168941b909a20bf5386ec767e6cd0d03d34249e0a00290c9c5
-  data.tar.gz: c69b120cd7847b4b2f8aca24a6f9a5ac609cd12fea9eb6f95502996b050ccb3994250588f1dc59772766a0c3334f147906b7c6c79db213c51cedbead4cb4e09d
+  metadata.gz: 504a5fd50aa71a6785546e6a5a437f5b6d4dcb864f1006344f656d93135ca63dddd30de2105362a5382afd0fe19a87b5830ee5fd3344a302a14509f494319f20
+  data.tar.gz: bd83dbcc8eb058cf581a4466c94edea750c7ada17bcbd9ac150ad905c51d65859d02a3cea1d65adb4c0a9ebd4ca8f77fbd655b1a14cf74bb3cfa2f2f0b0f206c

data/README.md

@@ -1,5 +1,10 @@
 # Shield AST - Application Security Testing CLI
 
+[![Gem Version](https://badge.fury.io/rb/shield_ast.svg)](https://badge.fury.io/rb/shield_ast)
+[![Build Status](https://github.com/JAugusto42/shield_ast/actions/workflows/main.yml/badge.svg)](https://github.com/JAugusto42/shield_ast/actions)
+[![Downloads](https://img.shields.io/gem/dt/shield_ast.svg)](https://rubygems.org/gems/shield_ast)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 **Shield AST** is a powerful command-line tool for **Application Security Testing**, combining multiple open-source scanners into a single workflow. With `ast`, you can run **SAST** (Static Application Security Testing), **SCA** (Software Composition Analysis), and **IaC** (Infrastructure as Code) analysis quickly and automatically, helping you identify and fix vulnerabilities early in the development lifecycle.
 
 ---
@@ -44,7 +49,38 @@ ast [command] [options]
 - **`--version`** – Show the AST version.
 
 ---
+## ✨ NEW: AI-Powered False Positive Analysis
+
+Shield AST can use the **Google Gemini API** to automatically analyze findings and flag potential false positives, helping you focus on what matters most.
+
+### How to Enable It
+
+To activate this feature, you need a Google AI API key.
+
+### 1. Get Your API Key
+First, you'll need a Google Gemini API key to enable AI analysis.
+
+1.  Navigate to **[Google AI Studio](https://aistudio.google.com/app/apikey)**.
+2.  Click **"Create API key"** (you may need to sign in with your Google account).
+3.  Copy the key once it's generated.
 
+### 2. Configure Your Environment
+Next, export the API key as an environment variable in your terminal.
+
+```bash
+# Replace with your actual API key
+export GEMINI_API_KEY="YOUR_API_KEY_HERE"
+````
+📌 Tip: This command is temporary and only lasts for the current terminal session.
+To make it permanent, add the line above to your shell's configuration file (e.g., ~/.zshrc or ~/.bash_profile).
+
+The tool defaults to the free gemini-2.5-flash model.
+If you have access to a more powerful model,
+you can specify it by setting the optional GEMINI_MODEL variable:
+
+```bash
+export GEMINI_MODEL="gemini-2.5-pro"
+```
 ## 📌 Examples
 
 ```bash

data/lib/shield_ast/ai_analyzer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "gemini-ai"
+
+module ShieldAst
+  class AiAnalyzer
+    attr_reader :model_name, :finding
+
+    def initialize(finding)
+      @model_name = ENV.fetch("GEMINI_MODEL", "gemini-2.5-flash")
+      @finding = finding
+    end
+
+    def call
+      check_for_false_positive
+    end
+
+    private
+
+    def check_for_false_positive
+      file_path = finding["path"]
+      line = finding.dig("start", "line")
+      message = finding.dig("extra", "message") || finding["check_id"] || "N/A"
+      code_snippet = extract_code_snippet(file_path, line)
+      prompt = prompt(message, code_snippet, file_path, line)
+
+      begin
+        request_body = { contents: { role: "user", parts: { text: prompt } } }
+        response = client.generate_content(request_body)
+        result_text = response.dig("candidates", 0, "content", "parts", 0, "text")&.strip
+
+        return "\e[33m ⚠️ (Possible False Positive)\e[0m" if result_text == "FALSE_POSITIVE"
+        return "\e[36m 🛡️ (Verified by AI)\e[0m" if result_text == "TRUE_POSITIVE"
+      rescue StandardError
+        puts "\e[31m[!] AI analysis failed.\e[0m"
+      end
+
+      ""
+    end
+
+    def client
+      @client ||= Gemini.new(
+        credentials: {
+          service: "generative-language-api",
+          api_key: ENV["GEMINI_API_KEY"]
+        },
+        options: { model: model_name }
+      )
+    end
+
+    def prompt(message, code_snippet, file_path, line)
+      <<~PROMPT
+        Analyze the following security finding. Based on the code and the description, is it more likely to be a true positive or a false positive?
+
+        **Finding:** #{message}
+        **File:** #{file_path || "N/A"}:#{line || "N/A"}
+
+        **Code:**
+        ```
+        #{code_snippet}
+        ```
+
+        Respond with ONLY ONE of the following words: `TRUE_POSITIVE`, `FALSE_POSITIVE`, or `UNCERTAIN`.
+      PROMPT
+    end
+
+    def extract_code_snippet(file_path, line_number, context_lines = 10)
+      return "Code snippet not available (file not found)." unless file_path && File.exist?(file_path)
+      return "Code snippet not available (line number not specified)." unless line_number
+
+      lines = File.readlines(file_path)
+      start_line = [0, line_number - 1 - context_lines].max
+      end_line = [lines.length - 1, line_number - 1 + context_lines].min
+
+      snippet = []
+      (start_line..end_line).each do |i|
+        line_prefix = i + 1 == line_number ? ">> #{i + 1}: " : "   #{i + 1}: "
+        snippet << "#{line_prefix}#{lines[i].chomp}"
+      end
+      snippet.join("\n")
+    rescue StandardError => e
+      "Could not read code snippet: #{e.message}"
+    end
+  end
+end

data/lib/shield_ast/iac.rb

@@ -1,25 +1,33 @@
 # frozen_string_literal: true
 
-require "English"
 require "json"
+require "open3"
 
 module ShieldAst
+  # Wraps the logic for running Infrastructure as Code (IaC) scans using Semgrep.
   class IaC
     def self.scan(path)
-      # Execute Semgrep with IaC-specific rulesets
-      cmd = "semgrep --config=r/terraform --config=r/kubernetes --config=r/docker --config=r/yaml --json --quiet #{path}"
-      output = `#{cmd}`
+      cmd = [
+        "semgrep", "scan",
+        "--config", "r/terraform",
+        "--config", "r/kubernetes",
+        "--config", "r/docker",
+        "--config", "r/yaml",
+        "--json", "--quiet",
+        path
+      ]
 
-      if $CHILD_STATUS.success? && !output.strip.empty?
+      stdout, _stderr, status = Open3.capture3(*cmd)
+
+      if status.success? && !stdout.strip.empty?
         begin
-          report = JSON.parse(output)
+          report = JSON.parse(stdout)
           return { "results" => report["results"] || [] }
         rescue JSON::ParserError
           return { "results" => [] }
         end
       end
 
-      # Fallback if semgrep fails
       { "results" => [] }
     end
   end

data/lib/shield_ast/sast.rb

@@ -5,10 +5,12 @@ require "json"
 require "open3"
 
 module ShieldAst
-  # Runs SAST analysis using Semgrep.
+  # Wraps the logic for running SAST scan using Semgrep.
   class SAST
     def self.scan(path)
-      cmd = ["semgrep", "scan", path, "--json", "--disable-version-check"]
+      cmd = [
+        "semgrep", "scan", "--config", "p/r2c-ci", "--config", "p/secrets", "--json", "--disable-version-check", path
+      ]
       stdout, stderr, status = Open3.capture3(*cmd)
 
       if status.success?

data/lib/shield_ast/sca.rb

@@ -4,6 +4,7 @@ require "json"
 
 module ShieldAst
   class SCA
+    # Wraps the logic for running SCA scan using Osv Scanner.
     def self.scan(path)
       puts "Scanning path: #{path}" if ENV["DEBUG"]
 

data/lib/shield_ast/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ShieldAst
-  VERSION = "1.2.1"
+  VERSION = "1.3.0"
 end

data/lib/shield_ast.rb

@@ -1,13 +1,15 @@
-# lib/shield_ast/main.rb
 # frozen_string_literal: true
 
 require_relative "shield_ast/version"
 require_relative "shield_ast/runner"
+require_relative "shield_ast/ai_analyzer"
+
 require "json"
 require "fileutils"
 require "erb"
 require "prawn"
 require "prawn/table"
+require "gemini-ai"
 
 # Main module for the Shield AST gem.
 module ShieldAst
@@ -15,13 +17,13 @@ module ShieldAst
 
   # Main class for the Shield AST command-line tool.
   class Main
-    SCAN_DATA_FILE = File.join(Dir.pwd, "lib", "reports", "scan_data.json")
-    REPORT_JSON_FILE = File.join(Dir.pwd, "lib", "reports", "scan_report.json")
-    REPORT_PDF_FILE = File.join(Dir.pwd, "lib", "reports", "scan_report.pdf")
-    PDF_TEMPLATE = File.join(__dir__, "reports", "templates", "pdf_report_template.rb")
+    SCAN_DATA_FILE = File.join(Dir.pwd, "reports", "scan_data.json")
+    REPORT_JSON_FILE = File.join(Dir.pwd, "reports", "scan_report.json")
+    REPORT_PDF_FILE = File.join(Dir.pwd, "reports", "scan_report.pdf")
+    PDF_TEMPLATE = File.join(Dir.pwd, "reports", "templates", "pdf_report_template.rb")
 
     def self.call(args)
-      ascii_banner
+      banner
 
       unless scanner_exists?("osv-scanner") && scanner_exists?("semgrep")
         puts "\e[31m[!] ERROR:\e[0m Required tools not found."
@@ -61,10 +63,10 @@ module ShieldAst
 
       reports = Runner.run(options, path) || {}
 
+      display_reports(reports)
+
       end_time = Time.now
       execution_time = end_time - start_time
-
-      display_reports(reports, execution_time)
       save_scan_data(reports, execution_time)
     end
 
@@ -81,6 +83,9 @@ module ShieldAst
       FileUtils.mkdir_p(File.dirname(SCAN_DATA_FILE))
       File.write(SCAN_DATA_FILE, JSON.pretty_generate(data))
       puts "Scan data saved to: #{SCAN_DATA_FILE}"
+
+      puts "\n🕒 Duration:: #{format_duration(execution_time)}"
+      puts "✅ DONE."
     end
 
     def self.load_scan_data
@@ -197,37 +202,55 @@ module ShieldAst
       end
     end
 
-    def self.display_reports(reports, execution_time)
-      total_issues = 0
+    def self.display_reports(reports)
+      gemini_enabled = !ENV["GEMINI_API_KEY"].to_s.empty?
 
-      reports.each do |type, report_data|
-        results = report_data[:results] || report_data["results"] || []
-        total_issues += results.length
+      total_issues = flatten_findings(reports).length
+
+      if total_issues.zero?
+        puts "✅ No security issues found! Your code looks clean."
+        return
+      end
+
+      puts "\nScan Results:"
+      if gemini_enabled
+        model = ENV.fetch("GEMINI_MODEL", "gemini-2.5-flash")
+        puts "\e[34m🔑 Gemini API key found. False positive analysis enabled (this may slow down the scan).\e[0m"
+        puts "🤖 AI Model: #{model}"
+      end
 
+      reports.each do |scan_type, report_data|
+        next unless report_data.is_a?(Hash)
+
+        results = report_data[:results] || report_data["results"] || []
         next if results.empty?
 
         sorted_results = sort_by_severity(results)
+
         top_results = sorted_results.first(5)
-        remaining_count = results.length - top_results.length
+        remaining_count = sorted_results.length - top_results.length
 
-        puts "\n#{get_scan_icon(type)} #{type.to_s.upcase} (#{results.length} #{results.length == 1 ? "issue" : "issues"}#{remaining_count.positive? ? ", showing top 5" : ""})"
+        puts "\n#{get_scan_icon(scan_type.to_sym)} #{scan_type.to_s.upcase} (#{results.length} #{results.length == 1 ? "issue" : "issues"}#{remaining_count.positive? ? ", showing top 5" : ""})"
         puts "-" * 60
 
-        format_report(top_results, type)
+        top_results.each do |result|
+          if scan_type.to_sym == :sca && has_sca_format?(result)
+            format_sca_result(result)
+          else
+            fp_indicator = gemini_enabled ? ShieldAst::AiAnalyzer.new(result).call : ""
+            format_default_result(result, fp_indicator)
+          end
+          puts ""
+        end
 
         if remaining_count.positive?
-          puts "     ... and #{remaining_count} more #{remaining_count == 1 ? "issue" : "issues"} (run with --verbose to see all)"
+          puts "... and #{remaining_count} more #{remaining_count == 1 ? "issue" : "issues"}. See the full report for details."
         end
       end
 
-      puts "\n✅ Scan finished in: #{format_duration(execution_time)}"
-
-      if total_issues.zero?
-        puts "✅ No security issues found! Your code looks clean."
-      else
-        severity_summary = calculate_severity_summary(reports)
-        puts "📊 Total: #{total_issues} findings {error_count: #{severity_summary[:error_count]}, warning_count: #{severity_summary[:warning_count]}, info_count: #{severity_summary[:info_count]}}"
-      end
+      puts "\n#{"=" * 60}"
+      severity_summary = calculate_severity_summary(reports)
+      puts "📊 Total: #{total_issues} findings {error_count: #{severity_summary[:error_count]}, warning_count: #{severity_summary[:warning_count]}, info_count: #{severity_summary[:info_count]}}"
     end
 
     def self.sort_by_severity(results)
@@ -317,19 +340,22 @@ module ShieldAst
       puts "     📁 #{result[:file] || result["file"]} | #{(result[:description] || result["description"] || "")[0..80]}#{(result[:description] || result["description"] || "").length > 80 ? "..." : ""}"
     end
 
-    def self.format_default_result(result)
-      severity_icon = get_severity_icon(result[:severity] || result["severity"] || result[:extra]&.[](:severity) || result["extra"]&.[]("severity"))
-      message = result[:extra]&.[](:message) || result["extra"]&.[]("message") || "Unknown issue"
-      title = message.split(".")[0].strip
-      file_info = "#{File.basename(result[:path] || result["path"] || "N/A")}:#{result[:start]&.[](:line) || result["start"]&.[]("line") || "N/A"}"
+    def self.format_default_result(result, fp_indicator = "")
+      severity_icon = get_severity_icon(result.dig("extra", "severity") || result["severity"])
+      message = result.dig("extra", "message") || result["check_id"] || "Unknown issue"
+      title = message.split(".").first&.strip || message
+      file_info = "#{result["path"] || "N/A"}:#{result.dig("start", "line") || "N/A"}"
 
-      puts "  #{severity_icon} #{title}"
-      puts "     📁 #{file_info} | #{(result[:extra]&.[](:message) || result["extra"]&.[]("message") || "No description available")[0..80]}..."
+      puts "  #{severity_icon} #{title}#{fp_indicator}"
+      puts "     📁 #{file_info}"
+      puts "        #{message}"
     end
 
     def self.parse_args(args)
-      options = { command: nil, path: nil, sast: false, sca: false, iac: false, help: false, version: false,
-                  output: nil }
+      options = {
+        command: nil, path: nil, sast: false, sca: false, iac: false, help: false, version: false, output: nil
+      }
+
       args.each_with_index do |arg, index|
         case arg
         when "scan" then options[:command] = "scan"
@@ -347,6 +373,18 @@ module ShieldAst
       options
     end
 
+    def self.flatten_findings(reports)
+      findings = []
+      reports.each do |scan_type, report_data|
+        results = report_data[:results] || report_data["results"] || []
+
+        results.each do |result|
+          findings << result.merge(scan_type: scan_type.to_sym)
+        end
+      end
+      sort_by_severity(findings)
+    end
+
     def self.show_help
       puts <<~HELP
         ast - A powerful command-line tool for Application Security Testing
@@ -374,11 +412,16 @@ module ShieldAst
       HELP
     end
 
-    def self.ascii_banner
-      puts <<~BANNER
-        [>>> SHIELD AST <<<]
-        powered by open source (semgrep + osv-scanner) \n
-      BANNER
+    def self.banner
+      yellow = "\e[33m"
+      reset = "\e[0m"
+      version_string = "Shield AST - v#{ShieldAst::VERSION}"
+      line_length = 42
+
+      puts "#{yellow}┌" + "─" * line_length + "┐#{reset}"
+      puts "#{yellow}│#{reset} #{version_string.ljust(line_length - 1)}#{yellow}│#{reset}"
+      puts "#{yellow}└" + "─" * line_length + "┘#{reset}"
+      puts ""
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shield_ast
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Jose Augusto
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: gemini-ai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -98,6 +112,7 @@ files:
 - exe/ast
 - lib/reports/templates/pdf_report_template.rb
 - lib/shield_ast.rb
+- lib/shield_ast/ai_analyzer.rb
 - lib/shield_ast/iac.rb
 - lib/shield_ast/runner.rb
 - lib/shield_ast/sast.rb