legion-rbac 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59a7e721e473fdb1e65fe31d2da68e7fc7fc0a65e2e077f199f62c98aaf78fb5
-  data.tar.gz: b59c16e31ab6f63b1f93947a6c47ba59c891c2275a4f73463f892f4c0a71d9a8
+  metadata.gz: db6027eb10e80db5c7fce237a53e1640036d4d30e73e2e468029054843df5c4f
+  data.tar.gz: dd520f3dc81753b13bb29bf41bd664bbb0acdd789697a50649f93f77c68d3655
 SHA512:
-  metadata.gz: c8431ff82ad752660da99454b4170999572d2c37259fe33605238fc4faa6fdabe3d5c50a29dfc0d40c2fb45225107e457f15ac1e14aa0d8c41f6985cb39aa855
-  data.tar.gz: aafee7d9c8e9a3a07974aae8b890a8120dda0a10906a45ec1e967745563db0c2eed90ae39d2e14603d383df900ef450add66484d00cd4254288c573d976a47f2
+  metadata.gz: e56a6e0e93987b829f04ca89c907753d893ec9d6907d7cf8f29d011b92b82906b249abac00fe3951142589b6ba8cbd8308fe0fd57b9d5974c708e00b744585f3
+  data.tar.gz: 5d47a2e7805ae8fcd242c1a7bcf2f916063adf8517831ec06b198f77c145b4734eaa9b36d4ce8450eebe17d5ff47c852abd8288ae9da9f6e115780f9bb152f45

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.9] - 2026-03-31
+
+### Added
+- `Legion::Rbac::CapabilityAudit` module: static analysis of extension source code to detect dangerous patterns (`system`, `exec`, `Open3`, backticks, `eval`, `Net::HTTP`, `Faraday`, `File.write`, `FileUtils`) and map them to required capabilities (`shell_execute`, `code_eval`, `network_outbound`, `filesystem_write`). Blocks extensions with undeclared capabilities in enforce mode, warns in warn mode. Configurable via `rbac.capability_audit` settings.
+- `Legion::Rbac::CapabilityAudit::AuditResult` value object with `blocked?`, `undeclared`, `detected_capabilities`, `declared_capabilities`, and `to_h` conversion.
+- `Legion::Rbac::CapabilityRegistry` module: thread-safe registry tracking which extensions have which capabilities. `register`, `for_extension`, `extensions_with`, `audit_result_for`, `all`, `registered?`, `clear!` methods.
+- `Legion::Rbac::PolicyEngine.evaluate_capability`: runtime RBAC gating for capabilities — checks if a principal's roles grant or deny a specific capability, with deny-always-wins semantics and dry-run support.
+- `Legion::Rbac::Role#capability_allowed?`: per-role capability check (denial takes precedence over grant).
+- `capability_grants` and `capability_denials` fields on all four built-in roles: admin (all granted), supervisor (shell + network + filesystem, code_eval denied), worker (network + filesystem, shell + eval denied), governance-observer (all denied).
+- `Legion::Rbac.audit_extension`: convenience method that audits an extension and registers it in the CapabilityRegistry.
+- `Legion::Rbac.authorize_capability!`: raises `AccessDenied` when a principal lacks the required capability.
+- `rbac.capability_audit` settings: `enabled` (default true), `mode` (enforce/warn), `undeclared_policy` (block).
+- 43 new specs (159 total) covering all three phases of the capability enforcement system.
+
 ## [0.2.8] - 2026-03-28
 
 ### Added

data/CLAUDE.md

@@ -2,7 +2,7 @@
 
 **Parent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
 **GitHub**: https://github.com/LegionIO/legion-rbac
-**Version**: 0.2.2
+**Version**: 0.2.7
 
 Optional RBAC gem for LegionIO. Vault-style flat policy model with deny-always-wins semantics.
 

data/Gemfile

@@ -9,5 +9,6 @@ group :test do
   gem 'rspec'
   gem 'rspec_junit_formatter'
   gem 'rubocop'
+  gem 'rubocop-legion'
   gem 'simplecov'
 end

data/README.md

@@ -2,7 +2,7 @@
 
 Role-based access control for LegionIO, following Vault-style flat policy patterns.
 
-**Version**: 0.2.2
+**Version**: 0.2.9
 
 ## Features
 
@@ -53,6 +53,36 @@ principal.profile       # => { first_name: "Jane", last_name: "Doe", ... }
 Legion::Rbac.authorize_execution!(principal: principal, runner_class: 'Legion::Extensions::LexHttp::Runners::Request', function: :get)
 ```
 
+### Capability Audit (Extension Security)
+
+Audit an extension's source code for dangerous patterns and enforce capability declarations:
+
+```ruby
+result = Legion::Rbac.audit_extension(
+  extension_name: 'lex-codegen',
+  source_path: '/path/to/lex-codegen/lib',
+  declared_capabilities: [:shell_execute, :filesystem_write]
+)
+result.blocked?               # => false (all capabilities declared)
+result.detected_capabilities  # => [:shell_execute, :filesystem_write]
+
+# Query the capability registry
+Legion::Rbac::CapabilityRegistry.for_extension('lex-codegen')
+# => [:filesystem_write, :shell_execute]
+
+Legion::Rbac::CapabilityRegistry.extensions_with(:shell_execute)
+# => ["lex-codegen", "lex-exec"]
+```
+
+### Capability Authorization
+
+Check if a principal's role allows a specific capability:
+
+```ruby
+Legion::Rbac.authorize_capability!(principal: principal, capability: :shell_execute, extension_name: 'lex-codegen')
+# Raises AccessDenied if the principal's role denies shell_execute
+```
+
 ### Dry-Run Check
 
 ```ruby

data/lib/legion/rbac/capability_audit.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Legion
+  module Rbac
+    module CapabilityAudit
+      PATTERN_TO_CAPABILITY = {
+        /\bKernel\.system\b|\bsystem\s*\(/     => :shell_execute,
+        /\bKernel\.exec\b|\bexec\s*\(/         => :shell_execute,
+        /\bOpen3\b/                            => :shell_execute,
+        /`[^`]+`/                              => :shell_execute,
+        /\bIO\.popen\b/                        => :shell_execute,
+        /\bKernel\.eval\b|\beval\s*\(/         => :code_eval,
+        /\bNet::HTTP\b/                        => :network_outbound,
+        /\bFaraday\b/                          => :network_outbound,
+        /\bHTTParty\b/                         => :network_outbound,
+        /\bFile\.(write|open|delete|rename)\b/ => :filesystem_write,
+        /\bFileUtils\b/                        => :filesystem_write
+      }.freeze
+
+      class AuditResult
+        attr_reader :extension_name, :detected_capabilities, :declared_capabilities,
+                    :undeclared, :allowed, :reason
+
+        def initialize(extension_name:, detected:, declared:, allowed:, reason: nil)
+          @extension_name = extension_name
+          @detected_capabilities = detected.uniq.sort
+          @declared_capabilities = declared.map(&:to_sym).uniq.sort
+          @undeclared = (@detected_capabilities - @declared_capabilities).sort
+          @allowed = allowed
+          @reason = reason
+        end
+
+        def blocked?
+          !@allowed
+        end
+
+        def to_h
+          hash = {
+            extension_name:        @extension_name,
+            allowed:               @allowed,
+            detected_capabilities: @detected_capabilities,
+            declared_capabilities: @declared_capabilities,
+            undeclared:            @undeclared
+          }
+          hash[:reason] = @reason if @reason
+          hash
+        end
+      end
+
+      class << self
+        def audit(extension_name:, source_path:, declared_capabilities: [])
+          return skip_result(extension_name, 'capability audit disabled') unless enabled?
+
+          return skip_result(extension_name, 'no source path') unless source_path && Dir.exist?(source_path.to_s)
+
+          detected = scan_source(source_path)
+          declared_syms = Array(declared_capabilities).map(&:to_sym)
+          undeclared = (detected.uniq - declared_syms)
+
+          if undeclared.empty?
+            AuditResult.new(
+              extension_name: extension_name,
+              detected:       detected,
+              declared:       declared_syms,
+              allowed:        true
+            )
+          else
+            handle_undeclared(extension_name, detected, declared_syms, undeclared)
+          end
+        end
+
+        def enabled?
+          settings = capability_audit_settings
+          settings[:enabled] != false
+        end
+
+        def mode
+          settings = capability_audit_settings
+          (settings[:mode] || 'enforce').to_s
+        end
+
+        private
+
+        def scan_source(source_path)
+          capabilities = []
+          Dir.glob(File.join(source_path, '**', '*.rb')).each do |file|
+            File.foreach(file) do |line|
+              PATTERN_TO_CAPABILITY.each do |pattern, capability|
+                capabilities << capability if line.match?(pattern)
+              end
+            end
+          end
+          capabilities.uniq
+        end
+
+        def handle_undeclared(extension_name, detected, declared, undeclared)
+          if mode == 'warn'
+            log_warning(extension_name, undeclared)
+            AuditResult.new(
+              extension_name: extension_name,
+              detected:       detected,
+              declared:       declared,
+              allowed:        true,
+              reason:         "undeclared capabilities (warn mode): #{undeclared.join(', ')}"
+            )
+          else
+            AuditResult.new(
+              extension_name: extension_name,
+              detected:       detected,
+              declared:       declared,
+              allowed:        false,
+              reason:         "undeclared capabilities: #{undeclared.join(', ')}"
+            )
+          end
+        end
+
+        def log_warning(extension_name, undeclared)
+          return unless defined?(Legion::Logging)
+
+          Legion::Logging.warn(
+            "CapabilityAudit: #{extension_name} uses undeclared capabilities: #{undeclared.join(', ')}"
+          )
+        end
+
+        def skip_result(extension_name, reason)
+          AuditResult.new(
+            extension_name: extension_name,
+            detected:       [],
+            declared:       [],
+            allowed:        true,
+            reason:         reason
+          )
+        end
+
+        def capability_audit_settings
+          return {} unless defined?(Legion::Settings)
+
+          Legion::Settings[:rbac]&.dig(:capability_audit) || {}
+        end
+      end
+    end
+  end
+end

data/lib/legion/rbac/capability_registry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module Legion
+  module Rbac
+    module CapabilityRegistry
+      class << self
+        def register(extension_name, capabilities:, audit_result: nil)
+          mon.synchronize do
+            entries[extension_name.to_s] = {
+              capabilities:  Array(capabilities).map(&:to_sym).uniq,
+              audit_result:  audit_result,
+              registered_at: Time.now
+            }
+          end
+        end
+
+        def for_extension(extension_name)
+          mon.synchronize do
+            entry = entries[extension_name.to_s]
+            entry ? entry[:capabilities] : []
+          end
+        end
+
+        def extensions_with(capability)
+          cap_sym = capability.to_sym
+          mon.synchronize do
+            entries.select { |_, entry| entry[:capabilities].include?(cap_sym) }.keys
+          end
+        end
+
+        def audit_result_for(extension_name)
+          mon.synchronize do
+            entry = entries[extension_name.to_s]
+            entry&.dig(:audit_result)
+          end
+        end
+
+        def all
+          mon.synchronize { entries.dup }
+        end
+
+        def registered?(extension_name)
+          mon.synchronize { entries.key?(extension_name.to_s) }
+        end
+
+        def clear!
+          mon.synchronize { @entries = {} }
+        end
+
+        private
+
+        def entries
+          @entries ||= {}
+        end
+
+        def mon
+          @mon ||= Monitor.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/rbac/config_loader.rb

@@ -9,11 +9,13 @@ module Legion
         roles_config ||= Legion::Settings[:rbac][:roles]
         roles_config.each_with_object({}) do |(name, config), index|
           index[name.to_sym] = Role.new(
-            name:        name,
-            description: config[:description] || '',
-            permissions: config[:permissions] || [],
-            deny:        config[:deny] || [],
-            cross_team:  config[:cross_team] || false
+            name:               name,
+            description:        config[:description] || '',
+            permissions:        config[:permissions] || [],
+            deny:               config[:deny] || [],
+            cross_team:         config[:cross_team] || false,
+            capability_grants:  config[:capability_grants] || [],
+            capability_denials: config[:capability_denials] || []
           )
         end
       end

data/lib/legion/rbac/policy_engine.rb

@@ -49,6 +49,44 @@ module Legion
         end
       end
 
+      def self.evaluate_capability(principal:, capability:, extension_name: nil, role_index: nil, enforce: nil)
+        role_index ||= Legion::Rbac.role_index || {}
+        enforce = Legion::Settings[:rbac][:enforce] if enforce.nil?
+
+        resolved_roles = resolve_roles(principal, role_index)
+
+        if resolved_roles.empty?
+          return build_capability_result(
+            allowed: false, reason: 'no roles assigned',
+            principal: principal, capability: capability,
+            extension_name: extension_name, enforce: enforce
+          )
+        end
+
+        denied = resolved_roles.any? { |role| role.capability_denials.include?(capability.to_sym) }
+        if denied
+          return build_capability_result(
+            allowed: false, reason: "capability #{capability} denied by role policy",
+            principal: principal, capability: capability,
+            extension_name: extension_name, enforce: enforce
+          )
+        end
+
+        granted = resolved_roles.any? { |role| role.capability_grants.include?(capability.to_sym) }
+        unless granted
+          return build_capability_result(
+            allowed: false, reason: "capability #{capability} not granted by any role",
+            principal: principal, capability: capability,
+            extension_name: extension_name, enforce: enforce
+          )
+        end
+
+        build_capability_result(
+          allowed: true, principal: principal, capability: capability,
+          extension_name: extension_name, enforce: enforce
+        )
+      end
+
       def self.build_result(allowed:, principal:, action:, resource:, enforce:, reason: nil)
         result = {
           allowed:      enforce ? allowed : true,
@@ -60,6 +98,18 @@ module Legion
         result[:would_deny] = true if !enforce && !allowed
         result
       end
+
+      def self.build_capability_result(allowed:, principal:, capability:, enforce:, extension_name: nil, reason: nil)
+        result = {
+          allowed:      enforce ? allowed : true,
+          capability:   capability.to_s,
+          principal_id: principal.id
+        }
+        result[:extension_name] = extension_name if extension_name
+        result[:reason] = reason if reason
+        result[:would_deny] = true if !enforce && !allowed
+        result
+      end
     end
   end
 end

data/lib/legion/rbac/role.rb

@@ -5,9 +5,11 @@ require 'legion/rbac/permission'
 module Legion
   module Rbac
     class Role
-      attr_reader :name, :description, :permissions, :deny_rules, :cross_team
+      attr_reader :name, :description, :permissions, :deny_rules, :cross_team,
+                  :capability_grants, :capability_denials
 
-      def initialize(name:, description: '', permissions: [], deny: [], cross_team: false)
+      def initialize(name:, description: '', permissions: [], deny: [], cross_team: false,
+                     capability_grants: [], capability_denials: [])
         @name = name.to_s
         @description = description
         @permissions = permissions.map do |p|
@@ -17,11 +19,20 @@ module Legion
           DenyRule.new(resource_pattern: d[:resource], above_level: d[:above_level])
         end
         @cross_team = cross_team
+        @capability_grants = Array(capability_grants).map(&:to_sym)
+        @capability_denials = Array(capability_denials).map(&:to_sym)
       end
 
       def cross_team?
         @cross_team == true
       end
+
+      def capability_allowed?(capability)
+        cap = capability.to_sym
+        return false if @capability_denials.include?(cap)
+
+        @capability_grants.include?(cap)
+      end
     end
   end
 end

data/lib/legion/rbac/settings.rb

@@ -12,7 +12,16 @@ module Legion
           static_assignments: [],
           route_permissions:  {},
           roles:              default_roles,
-          entra:              entra_defaults
+          entra:              entra_defaults,
+          capability_audit:   capability_audit_defaults
+        }
+      end
+
+      def self.capability_audit_defaults
+        {
+          enabled:           true,
+          mode:              'enforce',
+          undeclared_policy: 'block'
         }
       end
 
@@ -41,25 +50,27 @@ module Legion
 
       def self.worker_role
         {
-          description: 'Execute assigned runners within team scope',
-          permissions: [
+          description:        'Execute assigned runners within team scope',
+          permissions:        [
             { resource: 'runners/*', actions: %w[execute] },
             { resource: 'tasks/*', actions: %w[read create] },
             { resource: 'schedules/*', actions: %w[read] },
             { resource: 'workers/self', actions: %w[read] }
           ],
-          deny:        [
+          deny:               [
             { resource: 'runners/lex-extinction/*' },
             { resource: 'runners/lex-governance/*' },
             { resource: 'workers/*/lifecycle' }
-          ]
+          ],
+          capability_grants:  %w[network_outbound filesystem_write],
+          capability_denials: %w[shell_execute code_eval]
         }
       end
 
       def self.supervisor_role
         {
-          description: 'Manage workers and schedules within team scope',
-          permissions: [
+          description:        'Manage workers and schedules within team scope',
+          permissions:        [
             { resource: 'runners/*', actions: %w[execute] },
             { resource: 'tasks/*', actions: %w[read create delete] },
             { resource: 'schedules/*', actions: %w[read create update delete] },
@@ -67,28 +78,32 @@ module Legion
             { resource: 'extensions/*', actions: %w[read] },
             { resource: 'events/*', actions: %w[read] }
           ],
-          deny:        [
+          deny:               [
             { resource: 'runners/lex-extinction/escalate', above_level: 2 },
             { resource: 'workers/*/lifecycle/terminated' }
-          ]
+          ],
+          capability_grants:  %w[network_outbound filesystem_write shell_execute],
+          capability_denials: %w[code_eval]
         }
       end
 
       def self.admin_role
         {
-          description: 'Full access, cross-team capability',
-          permissions: [
+          description:        'Full access, cross-team capability',
+          permissions:        [
             { resource: '*', actions: %w[read create update delete execute manage] }
           ],
-          deny:        [],
-          cross_team:  true
+          deny:               [],
+          cross_team:         true,
+          capability_grants:  %w[shell_execute code_eval network_outbound filesystem_write],
+          capability_denials: []
         }
       end
 
       def self.governance_observer_role
         {
-          description: 'Read-only visibility across all teams for audit and compliance',
-          permissions: [
+          description:        'Read-only visibility across all teams for audit and compliance',
+          permissions:        [
             { resource: 'workers/*', actions: %w[read] },
             { resource: 'tasks/*', actions: %w[read] },
             { resource: 'events/*', actions: %w[read] },
@@ -96,8 +111,10 @@ module Legion
             { resource: 'extensions/*', actions: %w[read] },
             { resource: 'runners/lex-governance/*', actions: %w[read execute] }
           ],
-          deny:        [],
-          cross_team:  true
+          deny:               [],
+          cross_team:         true,
+          capability_grants:  [],
+          capability_denials: %w[shell_execute code_eval network_outbound filesystem_write]
         }
       end
     end

data/lib/legion/rbac/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Rbac
-    VERSION = '0.2.8'
+    VERSION = '0.2.9'
   end
 end

data/lib/legion/rbac.rb

@@ -12,6 +12,8 @@ require 'legion/rbac/store'
 require 'legion/rbac/entra_claims_mapper'
 require 'legion/rbac/middleware'
 require 'legion/rbac/routes'
+require 'legion/rbac/capability_audit'
+require 'legion/rbac/capability_registry'
 
 module Legion
   module Rbac
@@ -60,6 +62,31 @@ module Legion
         authorize!(principal: principal, action: :execute, resource: runner_path, **)
       end
 
+      def audit_extension(extension_name:, source_path:, declared_capabilities: [])
+        result = CapabilityAudit.audit(
+          extension_name:        extension_name,
+          source_path:           source_path,
+          declared_capabilities: declared_capabilities
+        )
+        CapabilityRegistry.register(
+          extension_name,
+          capabilities: result.detected_capabilities,
+          audit_result: result
+        )
+        result
+      end
+
+      def authorize_capability!(principal:, capability:, extension_name: nil)
+        result = PolicyEngine.evaluate_capability(
+          principal:      principal,
+          capability:     capability,
+          extension_name: extension_name
+        )
+        raise AccessDenied, result unless result[:allowed]
+
+        result
+      end
+
       private
 
       def build_runner_path(runner_class, function)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-rbac
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.2.9
 platform: ruby
 authors:
 - Esity
@@ -61,6 +61,8 @@ files:
 - docs/implementation-plan.md
 - legion-rbac.gemspec
 - lib/legion/rbac.rb
+- lib/legion/rbac/capability_audit.rb
+- lib/legion/rbac/capability_registry.rb
 - lib/legion/rbac/config_loader.rb
 - lib/legion/rbac/entra_claims_mapper.rb
 - lib/legion/rbac/kerberos_claims_mapper.rb