arbac_verifier 1.0.1 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e8293d45df6e6ac48d7923723d3b04899292bf34bf0696046bae3ddd2eb6dba
-  data.tar.gz: 84e90713d08d36b339de962531f7494f15580e59f10a6d6ebed5a2ed18f8a5b0
+  metadata.gz: 8d2452f09757b60bfc77afd2442fe5839b803097b61d05a442fe597dc1193e97
+  data.tar.gz: 2ea5b84270a4013b8f2f92da60960fc42423265d5f1dc7244fd14e547c3551bc
 SHA512:
-  metadata.gz: d781d6c1a8a0de56210e9c47abf4eae12e0559704309f99a6fe6a217dfe94774028004e83803261344280344b0d129a0caeac6290c0866684c18bd72f7b3f279
-  data.tar.gz: 4f585bf557ccbe4ba22d3d14b622a136731c14383c7c1edd9566e0141001512468b81c79386c9faae7e519d02b12d1371d06dd045bb569b4959a2c150eef5bbd
+  metadata.gz: 555c5df13ffe056fee4bc6a9f1df7be64fd6489b863b838a5f2a81e558358e538b0b9c27ccba5c0fc3f4b7034323e9b0b9fb13308b426ecbff5ac116b8a3ad87
+  data.tar.gz: 8ff9f08b8ab1d8c03956b8ff1a44b79fcf5daf072134d2ebbee18cc19beba8c58512c0d641107f82eeabdaf39cb6a5f7785bac1dc148495328e14fe7de437a05

data/README.md

@@ -0,0 +1,101 @@
+![logo.png](logo.png)
+
+[![codecov](https://codecov.io/github/stefanosello/arbac_verifier/branch/main/graph/badge.svg?token=VXWHKJUJR2)](https://codecov.io/github/stefanosello/arbac_verifier)
+[![Ruby Gem](https://github.com/stefanosello/arbac_verifier/actions/workflows/gem-push.yml/badge.svg?branch=main)](https://github.com/stefanosello/arbac_verifier/actions/workflows/gem-push.yml)
+[![Gem Version](https://badge.fury.io/rb/arbac_verifier.svg)](https://badge.fury.io/rb/arbac_verifier)
+[![Open Source? Yes!](https://badgen.net/badge/Open%20Source%20%3F/Yes%21/blue?icon=github)](https://github.com/Naereen/badges/)
+
+
+**ARBAC Verifier** is a Ruby gem designed to facilitate the modeling and verification of Administrative Role-Based Access Control (ARBAC) policies. With this tool, you can efficiently model ARBAC policies and perform verification tasks to determine if a specific role (`Goal`) can be achieved starting from a given set of states (user-to-role assignments).
+
+This gem is grounded in comprehensive theoretical foundations, which you can explore in detail through the [official security course slides](https://secgroup.dais.unive.it/wp-content/uploads/2020/04/arbac.pdf) provided by [Ca' Foscari University](https://www.unive.it/pag/13526) of Venice. 
+
+## Installation
+The `arbac_verifier` gem can be installed from [rubygems.org](https://rubygems.org/gems/arbac_verifier) from command line: 
+```{bash}
+gem install arbac_verifier
+```
+or by adding the following line to your `Gemfile` project:
+```{ruby}
+gem 'arbac_verifier', '~> 1.0', '>= 1.0.1'
+```
+
+## ARBAC definition file
+An ARBAC (Attribute-Based Role-Based Access Control) policy definition comprises four key components:
+- **Users**: A set of individuals who are part of the system under analysis.
+- **Roles**: A set of roles that can be assigned to or removed from users.
+- **Can-Assign Rules**: These rules specify which roles can be assigned to users. Each rule includes:
+  - The role that has the authority to make the assignment.
+  - The role to be assigned.
+  - Positive preconditions: Specific roles that the user must already possess to be eligible for the new role.
+  - Negative preconditions: Specific roles that the user must not possess to be eligible for the new role.
+- **Can-Revoke Rules**: These rules specify which roles can be revoked from users. Each rule includes:
+  - The role that has the authority to revoke.
+  - The role to be revoked. 
+
+This structure ensures that role assignments and revocations are controlled and based on the current state of the user's roles.
+In order to represent a policy based on this definition, we can use `arbac` files, which should follow this format:
+```
+Roles Teacher Student TA ;
+Users stefano alice bob ;
+UA <stefano,Teacher> <alice,TA> ;
+CR <Teacher,Student> <Teacher,TA> ;
+CA <Teacher,-Teacher&-TA,Student> <Teacher,-Student,TA> <Teacher,TA&-Student,Teacher> ;
+Goal Student ;
+``` 
+- Each line starts with an *header* that explains which information will be represented
+  - `Roles` and `Users` are straight forward
+  - `UA` are initial User Assignments, i.e. user-role assignments, where each item is a pair of `<user,role>`
+  - `CR` are Can-Revoke rules, where each item is a pair of `<revoker role, revokable role>`
+  - `CA` are Can-Assign rules, where each item is a tern of `<assigner role, <positive1&positive2&-negative1&-negative2>, assignable role>`
+  - `Goal` is not an ARBAC property: it is the target role for which the reachability should be verified
+- Each line ends with a `;`
+- Items of each line are space-separated
+
+## Usage
+Once installed, the gem can be used to manage different tasks related to arbac policies.
+```{Ruby}
+require 'arbac_verifier'
+require 'set
+
+# Create new Arbac instance from .arbac file
+policy0 = ArbacInstance.new(path: 'policy0.arbac')
+
+# Create new Arbac instance passing single attributes
+policy1 = ArbacInstance.new(
+  goal: :Student,
+  roles: [:Teacher, :Student, :TA].to_set,
+  users: ["stefano", "alice", "bob"].to_set,
+  user_to_role: [UserRole.new("stefano", :Teacher), UserRole.new("alice", :TA)].to_set,
+  can_assign_rules: [
+                      CanAssignRule.new(:Teacher, [].to_set, [:Teacher, :TA].to_set, :Student),
+                      CanAssignRule.new(:Teacher, [].to_set, [:Student].to_set, :TA),
+                      CanAssignRule.new(:Teacher, [:TA].to_set, [:Student].to_set, :Teacher)
+                    ].to_set,
+  can_revoke_rules: [CanRevokeRule.new(:Teacher, :Student), CanRevokeRule.new(:Teacher, :TA)].to_set
+)
+```
+
+Once the problem instance has been defined, the gem provides two simplification algorithms that can be used to reduce the size of the reachability problem.
+These algorithms do not modify the original policy and return a new simplified policy.
+```{Ruby}
+require 'arbac_verifier'
+
+# apply backward slicing
+policy0bs =  ArbacUtilsModule::backward_slicing(policy0)
+policy0fs = ArbacUtilsModule::forward_slicing(policy0)
+```
+A Role Reachability Problem solution can be computed using the `ArbacReachabilityVerifier` class.
+```{Ruby}
+require 'arbac_verifier'
+
+# Creare new reachability verifier instance starting from an .arbac file
+verifier0 = ArbacReachabilityVerifier.new(path: 'policy0.arbac')
+
+# or from an already created ArbacInstance
+verifier1 = ArbacReachabilityVerifier.new(instance: policy1)
+
+# and then compute reachability
+verifier0.verify # => true
+```
+**NB:** when a verifier instance is created starting from an `.arbac` file, backward and forward slicing are applied to the parsed policy.

data/lib/arbac_verifier/classes/arbac_instance.rb

@@ -29,9 +29,7 @@ class ArbacInstance
 
   sig { params(params: T.any(Symbol, T::Set[String], T::Set[Symbol], T::Set[UserRole], T::Set[CanAssignRule], T::Set[CanRevokeRule], String)).void }
   def initialize(**params)
-    unless params[:path].nil?
-      initialize_by_file_path(T.cast(params[:path], String))
-    else
+    if params[:path].nil?
       initialize_by_attributes(
         T.cast(params[:goal], Symbol),
         T.cast(params[:roles], T::Set[Symbol]),
@@ -40,6 +38,8 @@ class ArbacInstance
         T.cast(params[:can_assign_rules], T::Set[CanAssignRule]),
         T.cast(params[:can_revoke_rules], T::Set[CanRevokeRule])
       )
+    else
+      initialize_by_file_path(T.cast(params[:path], String))
     end
   end
 

data/lib/arbac_verifier/classes/arbac_reachability_verifier.rb

@@ -11,13 +11,14 @@ class ArbacReachabilityVerifier
   sig { returns ArbacInstance }
   attr_reader :instance
 
-  sig { params(args: T.any(String, ArbacInstance)).void }
-  def initialize(**args)
-    if !(args[:instance].nil?)
-      @instance = T.let(T.cast(args[:instance], ArbacInstance), ArbacInstance)
-    else
-      path = T.cast(args[:path], String)
+  sig { params(params: T.any(String, ArbacInstance)).void }
+  def initialize(**params)
+    if params[:instance].nil?
+      path = T.cast(params[:path], String)
       @instance = ArbacUtilsModule::forward_slicing(ArbacUtilsModule::backward_slicing(ArbacInstance.new(path: path)))
+    else
+      instance = T.cast(params[:instance], ArbacInstance)
+      @instance = instance
     end
   end
 

data/lib/arbac_verifier/classes/rules/can_assign_rule.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# typed: true
+# typed: strict
 require 'sorbet-runtime'
 
 class CanAssignRule

data/lib/arbac_verifier/classes/rules/can_revoke_rule.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# typed: true
+# typed: strict
 require 'sorbet-runtime'
 
 class CanRevokeRule

data/lib/arbac_verifier/exceptions/computation_timed_out_exception.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # Public: Specific exception to throw when a certain computation time exceeds a predefined limit
 class ComputationTimedOutException < StandardError
 end

data/lib/arbac_verifier/modules/arbac_utils_module.rb

@@ -1,7 +1,6 @@
-# typed: true
+# typed: strict
 require 'sorbet-runtime'
 
-# Collection of utilities to manipulate .arbac files (defining an ARBAC role reachability problem) to parse and eventually solve the problem
 module ArbacUtilsModule
   extend T::Sig
 

data/lib/arbac_verifier.rb

@@ -1 +1,2 @@
+# typed: strict
 require 'arbac_verifier/classes/arbac_reachability_verifier'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: arbac_verifier
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.5
 platform: ruby
 authors:
 - Stefano Sello
@@ -80,13 +80,15 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
-description: A simple solutor for role reachability problem instances expressed in
-  ARBAC format.
+description: "    A way to solve simple ARBAC role reachability problems, given an
+  .arbac definition file or a pre-built problem instance."
 email: sellostefano@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
+- README.md
 - lib/arbac_verifier.rb
 - lib/arbac_verifier/classes/arbac_instance.rb
 - lib/arbac_verifier/classes/arbac_reachability_verifier.rb
@@ -95,7 +97,7 @@ files:
 - lib/arbac_verifier/classes/user_role.rb
 - lib/arbac_verifier/exceptions/computation_timed_out_exception.rb
 - lib/arbac_verifier/modules/arbac_utils_module.rb
-homepage: https://rubygems.org/gems/arbac_verifier
+homepage: https://github.com/stefanosello/arbac_verifier
 licenses:
 - Apache-2.0
 metadata: {}
@@ -107,7 +109,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="