lex-cost-scanner 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c65ca54b3c8ef026aa4fa0d3549159b63b00df80b3abc0f1a0b96b6586e4ac0a
+  data.tar.gz: a0b4e81649991adffaf07a5cf1fef039471a91839c8a285e8b1a088b3d98559d
+SHA512:
+  metadata.gz: efadba80fb8343108fc6c231e7d7b801feddaba3080dc12f2fd8221ad23a22a9d2fda8abee23fb9c7c061446af607c73070c69a1b331df408f5de28ae7ba079b
+  data.tar.gz: e0befc34946b3ea011a04ffd026be4f3206bb781ce824d7c6c415f78fb46bb53ee4b29ffd9b6638ffeeb79a8e59a4fdc18e18bee0734c0bc38a20bab544aafa8

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0] - 2026-03-24
+
+### Added
+- Resource classifier with LLM + rule-based fallback (idle < 5% CPU, oversized 5-20%)
+- Findings store with deduplication by account + resource + finding type
+- Scanner runner: `scan_account`, `scan_all`, `scan_stats`
+- Reporter runner: `generate_report`, `format_slack_blocks`, `post_report`
+- WeeklyScan interval actor (604800s / 1 week)

data/README.md

@@ -0,0 +1,41 @@
+# lex-cost-scanner
+
+Cloud cost optimization scanner for LegionIO. Scans AWS/Azure accounts for idle and oversized resources, classifies findings via LLM (with rule-based fallback), deduplicates across scans, and delivers a weekly Slack Block Kit report.
+
+## Architecture
+
+- **WeeklyScan actor** — interval actor fires `scan_all` every 604,800 seconds (1 week)
+- **Scanner runner** — iterates configured accounts, fetches resources, classifies each one
+- **Classifier helper** — uses `legion-llm` if available; falls back to CPU utilization rules
+- **FindingsStore** — thread-safe in-memory store with dedup by `account_id:resource_id:finding_type`
+- **Reporter runner** — generates Slack Block Kit weekly summary and posts via `lex-slack`
+
+## Settings
+
+```yaml
+cost_scanner:
+  slack_webhook: "https://hooks.slack.com/services/..."
+  accounts:
+    - id: "123456789012"
+      cloud: "aws"
+    - id: "my-gcp-project"
+      cloud: "gcp"
+```
+
+## Classification Rules (rule-based fallback)
+
+| CPU Avg | Finding | Severity |
+|---------|---------|----------|
+| < 5%    | idle    | high     |
+| 5–20%   | oversized | medium |
+| >= 20%  | none    | —        |
+
+Resources costing less than $50/month are skipped (`MIN_MONTHLY_COST`).
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```

data/lib/legion/extensions/cost_scanner/actors/weekly_scan.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CostScanner
+      module Actors
+        class WeeklyScan < Legion::Extensions::Actors::Every
+          def time
+            604_800
+          end
+
+          def runner_class
+            'Legion::Extensions::CostScanner::Runners::Scanner'
+          end
+
+          def runner_function
+            'scan_all'
+          end
+
+          def run_now?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cost_scanner/helpers/classifier.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CostScanner
+      module Helpers
+        module Classifier
+          extend Constants
+
+          CLASSIFY_PROMPT = <<~PROMPT
+            Analyze this cloud resource and classify it. Reply with ONLY valid JSON:
+            {"finding_type":"idle|oversized|unused_reservation|orphaned_storage|rightsizing|none",
+             "severity":"critical|high|medium|low|info",
+             "estimated_monthly_savings":0.0,
+             "recommendation":"one sentence action"}
+
+            Resource: %<resource_type>s %<resource_id>s
+            Monthly cost: $%<monthly_cost>.2f
+            Utilization: %<utilization>s
+          PROMPT
+
+          module_function
+
+          def classify(resource_id:, resource_type:, monthly_cost:, utilization:)
+            if llm_available?
+              llm_classify(resource_id: resource_id, resource_type: resource_type,
+                           monthly_cost: monthly_cost, utilization: utilization)
+            else
+              result = rule_based_classify(utilization: utilization, monthly_cost: monthly_cost)
+              result.merge(resource_id: resource_id, resource_type: resource_type, method: :rule_based)
+            end
+          end
+
+          def rule_based_classify(utilization:, monthly_cost:)
+            cpu = utilization[:cpu_avg] || 100.0
+
+            if cpu < Constants::IDLE_CPU_THRESHOLD
+              { finding_type: :idle, severity: :high,
+                estimated_monthly_savings: monthly_cost,
+                recommendation: 'Terminate or stop idle resource' }
+            elsif cpu < Constants::OVERSIZED_CPU_THRESHOLD
+              savings = monthly_cost * 0.4
+              { finding_type: :oversized, severity: :medium,
+                estimated_monthly_savings: savings,
+                recommendation: 'Rightsize to smaller instance type' }
+            else
+              { finding_type: :none, severity: :info,
+                estimated_monthly_savings: 0.0,
+                recommendation: 'Resource is adequately utilized' }
+            end
+          end
+
+          def llm_classify(resource_id:, resource_type:, monthly_cost:, utilization:)
+            prompt = format(CLASSIFY_PROMPT, resource_type: resource_type, resource_id: resource_id,
+                                             monthly_cost: monthly_cost, utilization: utilization.inspect)
+            response = Legion::LLM.chat(
+              message: prompt,
+              caller: { extension: 'lex-cost-scanner', function: 'classify' }
+            )
+            parsed = Legion::JSON.load(response)
+            parsed[:finding_type] = parsed[:finding_type].to_sym
+            parsed[:severity] = parsed[:severity].to_sym
+            parsed.merge(resource_id: resource_id, resource_type: resource_type, method: :llm)
+          rescue StandardError
+            result = rule_based_classify(utilization: utilization, monthly_cost: monthly_cost)
+            result.merge(resource_id: resource_id, resource_type: resource_type, method: :rule_based_fallback)
+          end
+
+          def llm_available?
+            defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cost_scanner/helpers/constants.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CostScanner
+      module Helpers
+        module Constants
+          FINDING_TYPES = %i[idle oversized unused_reservation orphaned_storage rightsizing none].freeze
+          SEVERITIES = %i[critical high medium low info].freeze
+          IDLE_CPU_THRESHOLD = 5.0
+          OVERSIZED_CPU_THRESHOLD = 20.0
+          MIN_MONTHLY_COST = 50.0
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cost_scanner/helpers/findings_store.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CostScanner
+      module Helpers
+        module FindingsStore
+          @mutex = Mutex.new
+          @findings = {}
+
+          module_function
+
+          def dedup_key(account_id:, resource_id:, finding_type:, **)
+            "#{account_id}:#{resource_id}:#{finding_type}"
+          end
+
+          def record(account_id:, resource_id:, finding_type:, **attrs)
+            key = dedup_key(account_id: account_id, resource_id: resource_id, finding_type: finding_type)
+            now = Time.now
+
+            @mutex.synchronize do
+              if @findings.key?(key)
+                @findings[key][:last_seen] = now
+                @findings[key][:scan_count] += 1
+                return { new: false, key: key }
+              end
+
+              @findings[key] = {
+                account_id: account_id, resource_id: resource_id, finding_type: finding_type,
+                first_seen: now, last_seen: now, scan_count: 1, status: :new
+              }.merge(attrs)
+              { new: true, key: key }
+            end
+          end
+
+          def all
+            @mutex.synchronize { @findings.values.dup }
+          end
+
+          def new_since(time)
+            @mutex.synchronize { @findings.values.select { |f| f[:first_seen] >= time } }
+          end
+
+          def total_savings
+            @mutex.synchronize { @findings.values.sum { |f| f[:estimated_monthly_savings] || 0.0 } }
+          end
+
+          def top_by_savings(limit: 10)
+            @mutex.synchronize do
+              @findings.values
+                       .sort_by { |f| -(f[:estimated_monthly_savings] || 0.0) }
+                       .first(limit)
+            end
+          end
+
+          def stats
+            @mutex.synchronize do
+              { total: @findings.size,
+                total_savings: @findings.values.sum { |f| f[:estimated_monthly_savings] || 0.0 },
+                by_type: @findings.values.group_by { |f| f[:finding_type] }.transform_values(&:size) }
+            end
+          end
+
+          def reset!
+            @mutex.synchronize { @findings.clear }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cost_scanner/runners/reporter.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CostScanner
+      module Runners
+        module Reporter
+          def generate_report(limit: 10)
+            top = Helpers::FindingsStore.top_by_savings(limit: limit)
+            stats = Helpers::FindingsStore.stats
+
+            { total_savings: stats[:total_savings],
+              findings_count: stats[:total],
+              by_type: stats[:by_type],
+              top_findings: top,
+              generated_at: Time.now }
+          end
+
+          def format_slack_blocks(report:)
+            blocks = []
+            savings = format('%.2f', report[:total_savings])
+
+            blocks << { type: 'header', text: { type: 'plain_text', text: 'Weekly Cost Optimization Report' } }
+            blocks << { type: 'section', text: { type: 'mrkdwn',
+                                                 text: "*Total potential savings:* $#{savings}/month\n" \
+                                                       "*Findings:* #{report[:findings_count]}" } }
+            blocks << { type: 'divider' }
+
+            (report[:top_findings] || []).each_with_index do |finding, i|
+              blocks << { type: 'section', text: { type: 'mrkdwn',
+                                                   text: "*#{i + 1}. #{finding[:resource_id]}* (#{finding[:finding_type]})\n" \
+                                                         "Savings: $#{format('%.2f',
+                                                                             finding[:estimated_monthly_savings] || 0)}/month\n" \
+                                                         "#{finding[:recommendation]}" } }
+            end
+
+            blocks
+          end
+
+          def post_report(limit: 10)
+            report = generate_report(limit: limit)
+            format_slack_blocks(report: report)
+
+            webhook = report_webhook
+            if webhook && defined?(Legion::Extensions::Slack::Client)
+              message = "Cost Optimization: $#{format('%.2f', report[:total_savings])}/month in savings identified"
+              Legion::Extensions::Slack::Client.new.send_webhook(message: message, webhook: webhook)
+            end
+
+            { success: true, report: report }
+          rescue StandardError => e
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def report_webhook
+            return nil unless defined?(Legion::Settings)
+
+            config = Legion::Settings[:cost_scanner] || {}
+            config[:slack_webhook]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cost_scanner/runners/scanner.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CostScanner
+      module Runners
+        module Scanner
+          def scan_all
+            accounts = scanner_config[:accounts] || []
+            results = accounts.map { |acct| scan_account(account_id: acct[:id], cloud: acct[:cloud]) }
+
+            { success: true, accounts_scanned: results.size, results: results,
+              total_savings: Helpers::FindingsStore.total_savings }
+          end
+
+          def scan_account(account_id:, cloud: 'aws')
+            resources = fetch_resources(account_id: account_id, cloud: cloud)
+            findings_count = resources.count do |resource|
+              process_resource(account_id: account_id, resource: resource)
+            end
+
+            { success: true, account_id: account_id, scanned: resources.size,
+              findings: findings_count }
+          rescue StandardError => e
+            { success: false, account_id: account_id, error: e.message }
+          end
+
+          def scan_stats
+            Helpers::FindingsStore.stats
+          end
+
+          private
+
+          def scanner_config
+            return {} unless defined?(Legion::Settings)
+
+            Legion::Settings[:cost_scanner] || {}
+          end
+
+          def process_resource(account_id:, resource:)
+            return false if (resource[:monthly_cost] || 0) < Helpers::Constants::MIN_MONTHLY_COST
+
+            classification = Helpers::Classifier.classify(
+              resource_id: resource[:resource_id],
+              resource_type: resource[:resource_type],
+              monthly_cost: resource[:monthly_cost],
+              utilization: resource[:utilization] || {}
+            )
+            return false if classification[:finding_type] == :none
+
+            result = Helpers::FindingsStore.record(
+              account_id: account_id,
+              resource_id: resource[:resource_id],
+              resource_type: resource[:resource_type],
+              finding_type: classification[:finding_type],
+              severity: classification[:severity],
+              monthly_cost: resource[:monthly_cost],
+              estimated_monthly_savings: classification[:estimated_monthly_savings],
+              recommendation: classification[:recommendation]
+            )
+            result[:new]
+          end
+
+          def fetch_resources(_account_id:, _cloud: 'aws')
+            return [] unless defined?(Legion::Extensions::Http::Client)
+
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cost_scanner/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CostScanner
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/cost_scanner.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'cost_scanner/version'
+require_relative 'cost_scanner/helpers/constants'
+require_relative 'cost_scanner/helpers/classifier'
+require_relative 'cost_scanner/helpers/findings_store'
+require_relative 'cost_scanner/runners/scanner'
+require_relative 'cost_scanner/runners/reporter'
+
+require_relative 'cost_scanner/actors/weekly_scan' if defined?(Legion::Extensions::Actors::Every)
+
+module Legion
+  module Extensions
+    module CostScanner
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: lex-cost-scanner
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.11
+- !ruby/object:Gem::Dependency
+  name: legion-crypt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.9
+- !ruby/object:Gem::Dependency
+  name: legion-data
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.17
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.17
+- !ruby/object:Gem::Dependency
+  name: legion-json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: legion-logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+- !ruby/object:Gem::Dependency
+  name: legion-settings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+- !ruby/object:Gem::Dependency
+  name: legion-transport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.9
+description: Scans AWS/Azure accounts for idle resources, classifies findings via
+  LLM, delivers weekly Slack reports
+email:
+- matt@legionio.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/legion/extensions/cost_scanner.rb
+- lib/legion/extensions/cost_scanner/actors/weekly_scan.rb
+- lib/legion/extensions/cost_scanner/helpers/classifier.rb
+- lib/legion/extensions/cost_scanner/helpers/constants.rb
+- lib/legion/extensions/cost_scanner/helpers/findings_store.rb
+- lib/legion/extensions/cost_scanner/runners/reporter.rb
+- lib/legion/extensions/cost_scanner/runners/scanner.rb
+- lib/legion/extensions/cost_scanner/version.rb
+homepage: https://github.com/LegionIO/lex-cost-scanner
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Cloud cost optimization scanner for LegionIO
+test_files: []