[](logo.png)
Attribute-based access control (ABAC) SDK for Python.
[](https://github.com/kolotaev/vakt/actions)
[](https://app.codecov.io/gh/kolotaev/vakt/tree/master)
[](https://badge.fury.io/py/vakt)
[](https://raw.githubusercontent.com/kolotaev/vakt/master/LICENSE)
------
## Documentation
- [Documentation](#documentation)
- [Description](#description)
- [Concepts](#concepts)
- [Install](#install)
- [Usage](#usage)
- [Components](#components)
- [Policy](#policy)
- [Inquiry](#inquiry)
- [Rules](#rules)
- [Comparison-related](#comparison-related)
- [Logic-related](#logic-related)
- [List-related](#list-related)
- [Network-related](#network-related)
- [String-related](#string-related)
- [Inquiry-related](#inquiry-related)
- [Checker](#checker)
- [Guard](#guard)
- [Storage](#storage)
- [Memory](#memory)
- [MongoDB](#mongodb)
- [SQL](#sql)
- [Redis](#redis)
- [Migration](#migration)
- [Caching](#caching)
- [Caching `RegexChecker`](#caching-regexchecker)
- [Caching the entire Storage backend](#caching-the-entire-storage-backend)
- [Caching the Guard](#caching-the-guard)
- [JSON](#json)
- [Logging](#logging)
- [Audit](#audit)
- [Milestones](#milestones)
- [Benchmark](#benchmark)
- [Acknowledgements](#acknowledgements)
- [Development](#development)
- [License](#license)
### Description
Vakt is an attribute-based and policy-based access control ([ABAC](https://en.wikipedia.org/wiki/Attribute-based_access_control))
toolkit that is based on policies.
ABAC stands aside of RBAC and ACL models, giving you
a fine-grained control on definition of the rules that restrict an access to resources and is generally considered a
"next generation" authorization model.
In its form Vakt resembles [IAM Policies](https://github.com/awsdocs/iam-user-guide/blob/master/doc_source/access_policies.md), but
has a way nicer attribute managing.
See [concepts](#concepts) section for more details.
*[Back to top](#documentation)*
### Concepts
Given you have some set of resources, you can define a number of policies that will describe access to them
answering the following questions:
1. *What resources (resource) are being requested?*
1. *Who is requesting the resource?*
1. *What actions (action) are requested to be done on the asked resources?*
1. *What are the rules that should be satisfied in the context of the request itself?*
1. *What is resulting effect of the answer on the above questions?*
The overall diagram of `vakt` workflow is:
[](diagram.svg)
Vakt allows you to gain:
* Policy Based Access Control _(vakt is based on Policies that describe access rules, strategies to your resources)_
* Fine-Grained Authorization _(vakt Policies give you fine-grained control over resource's, subject's, action's and context's attributes)_
* Dynamic Authorization Management _(you can add Policies and change their attributes)_
* Externalized Authorization Management _(you can build own external AuthZ server with vakt, see examples)_
*[Back to top](#documentation)*
### Install
Vakt runs on Python >= 3.6.
PyPy implementation is supported as well.
Bare-bones installation with in-memory storage:
```bash
pip install vakt
```
For MongoDB storage:
```bash
pip install vakt[mongo]
```
For SQL storage:
```bash
pip install vakt[sql]
pip install $ANY_DB_DRIVER_OF_YOUR_CHOICE_SUPPORTED_BY_SQLALCHEMY
```
For Redis storage:
```bash
pip install vakt[redis]
```
Also see [redis-py](https://redis.readthedocs.io/en/stable/index.html) docs.
For example if `hiredis` is found in the system, it will be used as a faster parser.
However vakt doesn't enforce this dependency.
*[Back to top](#documentation)*
### Usage
A quick dive-in:
```python
import vakt
from vakt.rules import Eq, Any, StartsWith, And, Greater, Less
policy = vakt.Policy(
123456,
actions=[Eq('fork'), Eq('clone')],
resources=[StartsWith('repos/Google', ci=True)],
subjects=[{'name': Any(), 'stars': And(Greater(50), Less(999))}],
effect=vakt.ALLOW_ACCESS,
context={'referer': Eq('https://github.com')},
description="""
Allow to fork or clone any Google repository for
users that have > 50 and < 999 stars and came from Github
"""
)
storage = vakt.MemoryStorage()
storage.add(policy)
guard = vakt.Guard(storage, vakt.RulesChecker())
inq = vakt.Inquiry(action='fork',
resource='repos/google/tensorflow',
subject={'name': 'larry', 'stars': 80},
context={'referer': 'https://github.com'})
assert guard.is_allowed(inq)
```
Or if you prefer Amazon IAM Policies style:
```python
import vakt
from vakt.rules import CIDR
policy = vakt.Policy(
123457,
effect=vakt.ALLOW_ACCESS,
subjects=[r'<[a-zA-Z]+ M[a-z]+>'],
resources=['library:books:<.+>', 'office:magazines:<.+>'],
actions=['read', 'get'],
context={
'ip': CIDR('192.168.0.0/24'),
},
description="""
Allow all readers of the book library whose surnames start with M get and read any book or magazine,
but only when they connect from local library's computer
""",
)
storage = vakt.MemoryStorage()
storage.add(policy)
guard = vakt.Guard(storage, vakt.RegexChecker())
inq = vakt.Inquiry(action='read',
resource='library:books:Hobbit',
subject='Jim Morrison',
context={'ip': '192.168.0.220'})
assert guard.is_allowed(inq)
```
For more examples see [here](./examples).
*[Back to top](#documentation)*
### Components
#### Policy
Policy is a main object for defining rules for accessing resources.
The main parts reflect questions described in [Concepts](#concepts) section:
* resources - a list of resources. Answers: what is asked?
* subjects - a list of subjects. Answers: who asks access to resources?
* actions - a list of actions. Answers: what actions are asked to be performed on resources?
* context - rules that should be satisfied by the given inquiry's context.
* effect - If policy matches all the above conditions, what effect does it imply?
Can be either `vakt.ALLOW_ACCESS` or `vakt.DENY_ACCESS`
All `resources`, `subjects` and `actions` are described with
a list containing strings, regexes, [Rules](#rules) or dictionaries of strings (attributes) to [Rules](#rules).
Each element in list acts as logical OR. Each key in a dictionary of Rules acts as logical AND.
`context` can be described only with a dictionary of [Rules](#rules).
Depending on a way `resources`, `subjects`, `actions` are described, Policy can have either
String-based or Rule-based type. Can be inspected by `policy.type`.
This enforces the use of a concrete Checker implementation. See [Checker](#checker) for more.
```python
from vakt import Policy, ALLOW_ACCESS
from vakt.rules import CIDR, Any, Eq, NotEq, In
# Rule-based policy (defined with Rules and dictionaries of Rules)
Policy(
1,
description="""
Allow access to administration interface subcategories: 'panel', 'switch' if user is not
a developer and came from local IP address.
""",
actions=[Any()],
resources=[{'category': Eq('administration'), 'sub': In(['panel', 'switch'])}],
subjects=[{'name': Any(), 'role': NotEq('developer')}],
effect=ALLOW_ACCESS,
context={'ip': CIDR('127.0.0.1/32')}
)
# String-based policy (defined with regular expressions)
Policy(
2,
description="""
Allow all readers of the book library whose surnames start with M get and read any book or magazine,
but only when they connect from local library's computer
""",
effect=ALLOW_ACCESS,
subjects=['<[\w]+ M[\w]+>'],
resources=('library:books:<.+>', 'office:magazines:<.+>'),
actions=['<read|get>'],
context={'ip': CIDR('192.168.2.0/24')}
)
```
Basically you want to create some set of Policies that encompass access rules for your domain and store them for
making future decisions by the [Guard](#guard) component.
```python
st = MemoryStorage()
for p in policies:
st.add(p)
```
Additionally you can create Policies with predefined effect classes:
```python
from vakt import PolicyAllow, PolicyDeny, ALLOW_ACCESS, DENY_ACCESS
p = PolicyAllow(1, actions=['<read|get>'], resources=['library:books:<.+>'], subjects=['<[\w]+ M[\w]+>'])
assert ALLOW_ACCESS == p.effect
p = PolicyDeny(2, actions=['<read|get>'], resources=['library:books:<.+>'], subjects=['<[\w]+ M[\w]+>'])
assert DENY_ACCESS == p.effect
```
*[Back to top](#documentation)*
#### Inquiry
Inquiry is an object that serves as a mediator between Vakt and outer world request for resource access. All you need
to do is take any kind of incoming request (REST request, SOAP, etc.) and build an `Inquiry` out of it in order to
feed it to Vakt. There are no concrete builders for Inquiry from various request types, since it's a very meticulous
process and you have hands on control for doing it by yourself. Let's see an example:
```python
from vakt import Inquiry
from flask import request, session
...
# if policies are defined on some subject's and resource's attributes with dictionaries of Rules:
inquiry2 = Inquiry(subject={'login': request.form['username'], 'role': request.form['user_role']},
action=request.form['action'],
resource={'book': session.get('book'), 'chapter': request.form['chapter']},
context={'ip': request.remote_addr})
# if policies are defined with strings or regular expressions:
inquiry = Inquiry(subject=request.form['username'],
action=request.form['action'],
resource=request.form['page'],
context={'ip': request.remote_addr})
```
Here we are taking form params from Flask request and additional request information. Then we transform them
to Inquiry. That's it.
Inquiry has several constructor arguments:
* resource - any | dictionary of str -> any. What resource is being asked to be accessed?
* action - any | dictionary str -> any. What is being asked to be done on the resource?
* subject - any | dictionary str -> any. Who asks for it?
* context - dictionary str -> any. What is the context of the request?
If you were observant enough you might have noticed that Inquiry resembles Policy, where Policy describes multiple
variants of resource access from the owner side and Inquiry describes an concrete access scenario from consumer side.
*[Back to top](#documentation)*
#### Rules
Rules allow you to describe conditions directly on `action`, `subject`, `resource` and `context`
or on their attributes.
If at least one Rule in the Rule-set is not satisfied Inquiry is rejected by given Policy.
Attaching a Rule-set to a Policy is simple. Here are some examples:
```python
from vakt import Policy, rules
Policy(
...,
subjects=[{'name': rules.Eq('Tommy')}],
),
Policy(
...,
actions=[rules.Eq('get'), rules.Eq('list'), rules.Eq('read')],
),
Policy(
...,
context={
'secret': rules.string.Equal('.KIMZihH0gsrc'),
'ip': rules.net.CIDR('192.168.0.15/24')
},
)
```
There are a number of different Rule types, see below.
If the existing Rules are not enough for you, feel free to define your [own](./examples/extending.py).
##### Comparison-related
| Rule | Example in Policy | Example in Inquiry | Notes |
| ------------- |-------------|-------------|-------------|
| Eq | `'age': Eq(40)` | `'age': 40`| |
| NotEq | `'age': NotEq(40)` | `'age': 40`| |
| Greater | `'height': Greater(6.2)` | `'height': 5.8`| |
| Less | `'height': Less(6.2)` | `'height': 5.8`| |
| GreaterOrEqual | `'stars': GreaterOrEqual(300)` | `'stars': 77`| |
| LessOrEqual | `'stars': LessOrEqual(300)` | `'stars': 300`| |
##### Logic-related
| Rule | Example in Policy | Example in Inquiry | Notes |
| ------------- |-------------|-------------|-------------|
| Truthy | `'admin': Truthy()` | `'admin': user.is_admin()`| Evaluates on Inquiry creation |
| Falsy | `'admin': Falsy()` | `'admin': lambda x: x.is_admin()`| Evaluates on Inquiry creation |
| Not | `'age': Not(Greater(90))` | `'age': 40` | |
| And | `'stars': And(Greater(50), Less(89))` | `'stars': 78` | Also, attributes in dictionary of Rules act as AND logic |
| Or | `'stars': Or(Greater(50), Less(120), Eq(8888))` | `'stars': 78` | Also, rules in a list of, say, `actions` act as OR logic |
| Any | `actions=[Any()]` | `action='get'`, `action='foo'` | Placeholder that fits any value |
| Neither | `subjects=[Neither()]` | `subject='Max'`, `subject='Joe'` | Not very useful, left only as a counterpart of Any |
##### List-related
| Rule | Example in Policy | Example in Inquiry | Notes |
| ------------- |-------------|-------------|-------------|
| In | `'method': In('get', 'post')` | `'method': 'get'`| |
| NotIn | `'method': NotIn('get', 'post')` | `'method': 'get'`| |
| AllIn | `'name': AllIn('Max', 'Joe')` | `'name': ['Max', 'Joe']`| |
| AllNotIn | `'name': AllNotIn('Max', 'Joe')` | `'name': ['Max', 'Joe']`| |
| AnyIn | `'height': AnyIn(5.9, 7.5, 4.9)` | `'height': [7.55]`| |
| AnyNotIn | `'height': AnyNotIn(5.9, 7.5, 4.9)` | `'height': [7.55]`| |
##### Network-related
| Rule | Example in Policy | Example in Inquiry | Notes |
| ------------- |-------------|-------------|-------------|
| CIDR | `'ip': CIDR('192.168.2.0/24')` | `'ip': 192.168.2.4`| |
##### String-related
| Rule | Example in Policy | Example in Inquiry | Notes |
| ------------- |-------------|-------------|-------------|
| Equal | `'name': Equal('max', ci=True)` | `'name': 'Max'`| Aliased as `StrEqual`. Use instead of `Eq` it you want string-type check and case-insensitivity |
| PairsEqual | `'names': PairsEqual()` | `'names': ['Bob', 'Bob']`| Aliased as `StrPairsEqual` |
| RegexMatch | `'file': RegexMatch(r'\.rb$')` | `'file': 'test.rb'`| |
| StartsWith | `'file': StartsWith('logs-')` | `'file': 'logs-data-101967.log'`| Supports case-insensitivity |
| EndsWith | `'file': EndsWith('.log')` | `'file': 'logs-data-101967.log'`| Supports case-insensitivity |
| Contains | `'file': Contains('sun')` | `'file': 'observations-sunny-days.csv'`| Supports case-insensitivity |
##### Inquiry-related
Inquiry-related rules are useful if you want to express equality relation between inquiry elements or their attributes.
| Rule | Example in Policy | Example in Inquiry | Notes |
| ------------- |-------------|-------------|-------------|
| SubjectMatch | `resources=[{'id': SubjectMatch()}]` | `Inquiry(subject='Max', resource={'id': 'Max'})`| Works for the whole subject value or one of its attributes |
| ActionMatch | `subjects=[ActionMatch('id')]` | `Inquiry(subject='Max', action={'method': 'get', id': 'Max'})`| Works for the whole action value or one of its attributes |
| ResourceMatch | `subjects=[ResourceMatch('id')]` | `Inquiry(subject='Max', resource={'res': 'book', id': 'Max'})`| Works for the whole resource value or one of its attributes |
| SubjectEqual | `'data': SubjectEqual()` | `Inquiry(subject='Max')`| Works only for strings. Favor SubjectMatch |
| ActionEqual | `'data': ActionEqual()` | `Inquiry(action='get')`| Works only for strings. Favor ActionMatch |
| ResourceIn | `'data': ResourceIn()` | `Inquiry(resource='/books/')`| Works only for strings. Favor ResourceMatch |
*[Back to top](#documentation)*
#### Checker
Checker allows you to check whether Policy matches Inquiry by concrete field (`subject`, `action`, etc.). It's used
internally by [Guard](#guard), but you should be aware of Checker types:
* RulesChecker - universal type that is used to check match of Policies defined with Rules or dictionaries of Rules
(Rule-based Policy type). It gives you the highest flexibility.
Most of the time you will use this type of Polices and thus this type of a Checker.
Besides, it's much more performant than RegexChecker. See [benchmark](#benchmark) for more details.
```python
from vakt import RulesChecker
ch = RulesChecker()
# etc.
```
* RegexChecker - checks match by regex test for policies defined with strings and regexps (String-based Policy type).
This means that all you Policies
can be defined in regex syntax (but if no regex defined in Policy falls back to simple string equality test) - it
gives you better flexibility compared to simple strings, but carries a burden of relatively slow performance.
You can configure a LRU cache size to adjust performance to your needs:
```python
from vakt import RegexChecker
ch = RegexChecker(2048)
ch2 = RegexChecker(512)
# etc.
```
See [benchmark](#benchmark) for more details.
Syntax for description of Policy fields is:
```
'<foo.*>'
'foo<[abc]{2}>bar'
'foo<\w+>'
'foo'
```
Where `<>` are delimiters of a regular expression boundaries part. Custom Policy can redefine them by overriding
`start_tag` and `end_tag` properties. Generally you always want to use the first variant: `<foo.*>`.
Due to relatively slow performance of regular expressions execution we recommend to define your policies in
regex syntax only when you really need it, in other cases use simple strings:
both will work perfectly (and now swiftly!) with RegexChecker.
**NOTE. All regex checks are performed in a case-sensitive way by default.
Even thought some storages (e.g. MemoryStorage) allow you to specify regex modifiers within the regex string, we do not translate regex modifiers to all storages (e.g. SQLStorage). Also see warning below**
**WARNING. Please note, that storages have varying level of regexp support. For example,
most SQL databases allow to use POSIX metacharacters whereas python `re` module
and thus MemoryStorage does not. So, while defining policies you're safe and sound
as long as you understand how storage of your choice handles the regexps you specified.**
* StringExactChecker - the most quick checker:
```
Checker that uses exact string equality. Case-sensitive.
E.g. 'sun' in 'sunny' - False
'sun' in 'sun' - True
```
* StringFuzzyChecker - quick checker with some extent of flexibility:
```
Checker that uses fuzzy substring equality. Case-sensitive.
E.g. 'sun' in 'sunny' - True
'sun' in 'sun' - True
```
Note, that some [Storage](#storage) handlers can already check if Policy fits Inquiry in
`find_for_inquiry()` method by performing specific to that storage queries - Storage can (and generally should)
decide on the type of actions based on the checker class passed to [Guard](#guard) constructor
(or to `find_for_inquiry()` directly).
Regardless of the results returned by a Storage the Checker is always the last row of control
before Vakt makes a decision.
*[Back to top](#documentation)*
#### Guard
Guard component is a main entry point for Vakt to make a decision. It has one method `is_allowed` that passed an
[Inquiry](#inquiry) gives you a boolean answer: is that Inquiry allowed or not?
Guard is constructed with [Storage](#storage) and [Checker](#checker).
__Policies that have String-based type won't match if RulesChecker is used and vise-versa.__
```python
st = MemoryStorage()
# And persist all our Policies so that to start serving our library.
for p in policies:
st.add(p)
guard = Guard(st, RulesChecker())
if guard.is_allowed(inquiry):
return "You've been logged-in", 200
else:
return "Go away, you violator!", 401
```
To gain best performance read [Caching](#caching) section.
*[Back to top](#documentation)*
#### Storage
Storage is a component that gives an interface for manipulating [Policies](#policy) persistence in various places.
It provides the following methods:
```python
add(policy) # Store a Policy
get(uid) # Retrieve a Policy by its ID
get_all(limit, offset) # Retrieve all stored Policies (with pagination)
retrieve_all(batch) # Retrieve all existing stored Policies (without pagination)
update(policy) # Store an updated Policy
delete(uid) # Delete Policy from storage by its ID
find_for_inquiry(inquiry) # Retrieve Policies that match the given Inquiry
```
Storage may have various backend implementations (RDBMS, NoSQL databases, etc.), they also may vary in performance
characteristics, so see [Caching](#caching) and [Benchmark](#benchmark) sections.
Vakt ships some Storage implementations out of the box. See below:
##### Memory
Implementation that stores Policies in memory. It's not backed by any file or something, so every restart of your
application will swipe out everything that was stored. Useful for testing.
```python
from vakt import MemoryStorage
storage = MemoryStorage()
```
##### MongoDB
MongoDB is chosen as the most popular and widespread NO-SQL database.
```python
from pymongo import MongoClient
from vakt.storage.mongo import MongoStorage
client = MongoClient('localhost', 27017)
storage = MongoStorage(client, 'database-name', collection='optional-collection-name')
```
Default collection name is 'vakt_policies'.
Actions are the same as for any Storage that conforms interface of `vakt.storage.abc.Storage` base class.
Beware that currently MongoStorage supports indexed and filtered-out `find_for_inquiry()` only for
StringExact, StringFuzzy and Regex (since MongoDB version 4.2 and onwards) checkers.
When used with the RulesChecker it simply returns all the Policies from the database.
##### SQL
SQL storage is backed by SQLAlchemy, thus it should support any RDBMS available for it:
MySQL, Postgres, Oracle, MSSQL, Sqlite, etc.
Given that we support various SQL databases via SQLAlchemy, we don't specify any DB-specific drivers in the vakt
dependencies. It's up to the user to provide a desired one. For example: `psycopg2` or `PyMySQL`.
Example for MySQL.
```python
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, scoped_session
from vakt.storage.sql import SQLStorage
engine = create_engine('mysql://root:root@localhost/vakt_db')
storage = SQLStorage(scoped_session=scoped_session(sessionmaker(bind=engine)))
# Don't forget to run migrations here (especially for the first time)
...
```
Beware that currently SQLStorage supports indexed and filtered-out `find_for_inquiry()` only for
StringExact, StringFuzzy and Regex checkers.
When used with the RulesChecker it simply returns all the Policies from the database.
Note that vakt focuses on testing SQLStorage functionality only for two most popular open-source databases:
MySQL and Postgres. Other databases support may have worse performance characteristics and/or bugs.
Feel free to report any issues.
##### Redis
Redis storage.
RedisStorate stores all Policies in a hash whose key is the collection name and the hash'es key value pairs are
Policy UID -> serialized Policy representation.
Default collection name is "vakt_policies".
You can use different Serializers. Any custom or one of the vakt's native.
Just pass it to the `RedisStorage` constructor.
Vakt is shipped with:
- `JSONSerializer`
- `PickleSerializer` - the fastest. Used as the default one.
Due to serialization/deserialization Redis is not as fast as simple `MemoryStorage`.
You can run the [benchmark](#benchmark) and check performance for your use-case.
```python
from redis import Redis
from vakt.storage.redis import RedisStorage
client = Redis('127.0.0.1', 6379)
yield RedisStorage(client, collection='optional-policies-collection-name')
client.flushdb()
client.close()
...
```
*[Back to top](#documentation)*
#### Migration
`vakt.migration` is a set of components that are useful from the perspective of the [Storage](#storage).
It's recommended to favor it over manual actions on DB schema/data
since it's aware of Vakt requirements to Policies data. But it's not mandatory, anyway.
However it's up to a particular Storage to decide whether it needs migrations or not.
It consists of 3 components:
* `Migration`
* `MigrationSet`
* `Migrator`
`Migration` allows you to describe data modifications between versions.
Each storage can have a number of `Migration` classes to address different releases with the order of the migration
specified in `order` property.
Should be located inside particular storage module and implement `vakt.storage.migration.Migration`.
Migration has 2 main methods (as you might guess) and 1 property:
- `up` - runs db "schema" upwards
- `down` - runs db "schema" downwards (rolls back the actions of `up`)
- `order` - tells the number of the current migration in a row
`MigrationSet` is a component that represents a collection of Migrations for a Storage.
You should define your own migration-set. It should be located inside particular storage module and implement
`vakt.storage.migration.MigrationSet`. It has 3 methods that lest unimplemented:
- `migrations` - should return all initialized Migration objects
- `save_applied_number` - saves a number of a lst applied up migration in the Storage for later reference
- `last_applied` - returns a number of a lst applied up migration from the Storage
`Migrator` is an executor of a migrations. It can execute all migrations up or down, or execute a particular migration
if `number` argument is provided.
Example usage:
```python
from pymongo import MongoClient
from vakt.storage.mongo import MongoStorage, MongoMigrationSet
from vakt.storage.migration import Migrator
client = MongoClient('localhost', 27017)
storage = MongoStorage(client, 'database-name', collection='optional-collection-name')
migrator = Migrator(MongoMigrationSet(storage))
migrator.up()
...
migrator.down()
...
migrator.up(number=2)
...
migrator.down(number=2)
```
*[Back to top](#documentation)*
### Caching
Vakt has several layers of caching, that serve a single purpose: speed up policy enforcement decisions.
In most situations and use-cases you might want to use them all, thus they are designed not to
interact with each other, but rather work in tandem
(nonetheless you are free to use any single layer alone or any combination of them).
That said let's look at all those layers.
##### Caching [`RegexChecker`](#checker)
It's relevant only for `RegexChecker` and allows to cache parsing and execution of regex-defined Policies,
which can be very expensive
due to inherently slow computational performance of regular expressions and vakt's parsing. When creating a `RegexChecker`
you can specify a cache size for an in-memory
[LRU (least recently used)](https://docs.python.org/3/library/functools.html#functools.lru_cache) cache. Currently
only python's native LRU cache is supported.
```python
# preferably size is a power of 2
chk = RegexChecker(cache_size=2048)
# or simply
chk = RegexChecker(2048)
# or 512 by default
chk = RegexChecker()
```
##### Caching the entire Storage backend
Some vakt's Storages may be not very clever at filtering Policies at `find_for_inquiry` especially when dealing with
Rule-based policies. In this case they return the whole set of the existing policies stored in the external storage.
Needless to say that it makes your application very heavy IO-bound and decreases performance for large policy sets
drastically. See [benchmark](#benchmark) for more details and exact numbers.
In such a case you can use `EnfoldCache` that wraps your main storage (e.g. MongoStorage) into another one
(it's meant to be some in-memory Storage). It returns you a Storage that behind the scene routes all the read-calls
(get, get_all, find_for_inquiry, ...) to an in-memory one and all modify-calls (add, update, delete) to your main Storage (
don't worry, in-memory Storage is kept up-to date with the main Storage). In case a requested policy is not found in in-memory Storage
it's considered a cache miss and a request is routed to a main Storage.
Also, in order to keep Storages in sync,
when you initialize `EnfoldCache` the in-memory Storage will fetch all the existing Policies from a main one -
therefore be forewarned that it might take some amount of time depending on the size of a policy-set.
Optionally you can call `populate` method after initialization, but in this case __do not ever call any modify-related methods of
EnfoldCache'd storage before `populate()`, otherwise Storages will be in an unsynchronized state and it'll
result in broken `Guard` functionality.__
```python
from vakt import EnfoldCache, MemoryStorage, Policy, Guard, RegexChecker
from vakt.storage.mongo import MongoStorage
storage = EnfoldCache(MongoStorage(...), cache=MemoryStorage())
storage.add(Policy(1, actions=['get']))
...
guard = Guard(storage, RegexChecker())
```
##### Caching the Guard
`Guard.is_allowed` it the the centerpiece of vakt. Therefore it makes ultimate sense to cache it.
And `create_cached_guard()` function allows you to do exactly that. You need to pass it a Storage, a Checker and a
maximum size of a cache. It will return you a tuple of: Guard, Storage and AllowanceCache instance:
- You must do all policies operations with the returned storage
(which is a slightly enhanced version of a Storage you provided to the function).
- The returned Guard is a normal vakt's `Guard`, but its `is_allowed` is cached with `AllowaceCache`.
- The returned cache is an instance of `AllowaceCache` and has a handy method `info` that provides current state of the cache.
How it works?
Only the first Inquiry will be passed to `is_allowed`, all the subsequent answers for similar Inquiries will be taken
from cache. `AllowanceCache` is rather coarse-grained and if you call Storage's `add`, `update` or `delete` the whole
cache will be invalided because the policy-set has changed. However for stable policy-sets it is a good performance boost.
By default `AllowanceCache` uses in-memory LRU cache and `maxsize` param is it's size. If for some reason it does not satisfy
your needs, you can pass your own implementation of a cache backend that is a subclass of
`vakt.cache.AllowanceCacheBackend` to `create_cached_guard` as a `cache` keyword argument.
```python
guard, storage, cache = create_cached_guard(MongoStorage(...), RulesChecker(), maxsize=256)
p1 = Policy(1, actions=[Eq('get')], resources=[Eq('book')], subjects=[Eq('Max')], effect=ALLOW_ACCESS)
storage.add(p1)
# Given we have some inquiries that tend to repeat
inq1 = Inquiry(action='get', resource='book', subject='Max')
inq2 = Inquiry(action='get', resource='book', subject='Jamey')
assert guard.is_allowed(inq1)
assert guard.is_allowed(inq1)
assert guard.is_allowed(inq1)
assert not guard.is_allowed(inq2)
assert guard.is_allowed(inq1)
assert guard.is_allowed(inq1)
# You can check cache state
assert 4 == cache.info().hits
assert 2 == cache.info().misses
assert 2 == cache.info().currsize
```
*[Back to top](#documentation)*
### JSON
All Policies, Inquiries and Rules can be JSON-serialized and deserialized.
For example, for a Policy all you need is just run:
```python
from vakt.policy import Policy
policy = Policy('1')
json_policy = policy.to_json()
print(json_policy)
# {"actions": [], "description": null, "effect": "deny", "uid": "1",
# "resources": [], "context": {}, "subjects": []}
policy = Policy.from_json(json_policy)
print(policy)
# <vakt.policy.Policy object at 0x1023ca198>
```
The same goes for Rules, Inquiries.
All custom classes derived from them support this functionality as well.
If you do not derive from Vakt's classes, but want this option, you can mix-in `vakt.util.JsonSerializer` class.
```python
from vakt.util import JsonSerializer
class CustomInquiry(JsonSerializer):
pass
```
*[Back to top](#documentation)*
### Logging
Vakt follows a common logging pattern for libraries:
Its corresponding modules log all the events that happen but the log messages by default are handled by `NullHandler`.
It's up to the outer code/application to provide desired log handlers, filters, levels, etc.
For example:
```python
import logging
root = logging.getLogger()
root.setLevel(logging.INFO)
root.addHandler(logging.StreamHandler())
... # here go all the Vakt calls.
```
Vakt logs can be comprehended in 2 basic levels:
1. *Error/Exception* - informs about exceptions and errors during Vakt work.
2. *Info* - informs about incoming inquiries, their resolution and policies responsible for this decisions
('vakt.guard' and 'vakt.audit' streams).
*[Back to top](#documentation)*
### Audit
Vakt allows you to not only watch the incoming inquiries and their resolution, but also keep track of the policies
that were responsible for allowing or rejecting the inquiry. It's done via audit logging.
Audit logging is implemented within a standard Python logging framework.
You can enable it by subscribing to an audit ('vakt.audit') logging "stream".
Example of configuration in the code:
```python
import logging
logger = logging.getLogger('vakt.audit')
logger.setLevel(logging.INFO)
fmt = 'msg: %(message)s | effect: %(effect)s | deciders: %(deciders)s | candidates: %(candidates)s | inquiry: %(inquiry)s'
fileHandler = logging.FileHandler('test.log')
fileHandler.setFormatter(logging.Formatter(fmt))
fileHandler.setLevel(logging.INFO)
logger.addHandler(fileHandler)
... # here go all the Vakt calls.
```
Vakt logs all audit records at the `INFO` level.
The formatter supports the following fields:
- message - the message that tells what and why happened in the audit.
- effect - effect that this decision has: 'allow' or 'deny'.
- candidates - potential policies that were filtered by storage and checkers and may be responsible for the decision.
- deciders - policies that are responsible for the final decision.
- inquiry - the inquiry in question.
- all the standard Python logging fields like time, level, module name, etc.
The `deciders` and `candidates` field can be logged in various ways depending on the the `audit_policies_cls`.
It can be passed to the `Guard` constructor.
Vakt has the following Audit Policies messages classes out of the box:
- PoliciesNopMsg
- PoliciesUidMsg (is the default one)
- PoliciesDescriptionMsg
- PoliciesCountMsg
Refer to their documentation on how they represent the policies.
**WARNING. Please note, that if you have Guard caching enabled, then audit records for the same subsequent inquiries won't be
logged because the calls are cached. However the log records from 'vakt.guard' stream will be always logged -
they will tell only was the inquiry allowed or not.**
*[Back to top](#documentation)*
### Milestones
Most valuable features to be implemented in the order of importance:
- [x] SQL Storage
- [x] Rules that reference Inquiry data for Rule-based policies
- [x] Caching mechanisms (for Storage and Guard)
- [ ] YAML-based language for declarative policy definitions
- [x] Enhanced audit logging
- [x] Redis Storage
*[Back to top](#documentation)*
### Benchmark
You can see how much time it takes for a single Inquiry to be processed given we have a number of unique Policies in a
Storage.
For [MemoryStorage](#memory) it measures the runtime of a decision-making process for all
the existing Policies when [Guard's](#guard) code iterates the whole list of Policies to decide if
Inquiry is allowed or not. In case of other Storages the mileage
may vary since they may return a smaller subset of Policies that fit the given Inquiry.
Don't forget that most external Storages add some time penalty to perform I/O operations.
The runtime also depends on a Policy-type used (and thus checker): RulesChecker performs much better than RegexChecker.
Example:
```bash
python3 benchmark.py --checker regex --storage memory -n 1000
```
Output is:
> Populating MemoryStorage with Policies<br />
> ......................<br />
> START BENCHMARK!<br />
> Number of unique Policies in DB: 1,000<br />
> Among them Policies with the same regexp pattern: 0<br />
> Checker used: RegexChecker<br />
> Storage used: MemoryStorage<br />
> Number of concurrent threads: 1<br />
> Decision for Inquiry took (mean: 0.2062 seconds. stdev: 0.0000)<br />
> Inquiry passed the guard? False<br />
Script usage:
```
usage: benchmark.py [-h] [-n [POLICIES_NUMBER]] [-s {mongo,memory,sql,redis}] [-d [SQL_DSN]] [-c {regex,rules,exact,fuzzy}]
[-t [THREADS]] [--regexp] [--same SAME] [--cache CACHE] [--serializer {json,pickle}]
Run vakt benchmark.
optional arguments:
-h, --help show this help message and exit
-n [POLICIES_NUMBER], --number [POLICIES_NUMBER]
number of policies to create in DB (default: 100000)
-s {mongo,memory,sql,redis}, --storage {mongo,memory,sql,redis}
type of storage (default: memory)
-d [SQL_DSN], --dsn [SQL_DSN]
DSN connection string for sql storage (default: sqlite:///:memory:)
-c {regex,rules,exact,fuzzy}, --checker {regex,rules,exact,fuzzy}
type of checker (default: regex)
-t [THREADS], --threads [THREADS]
number of concurrent requests (default: 1)
regex policy related:
--regexp should Policies be defined without Regex syntax? (default: True)
--same SAME number of similar regexps in Policy
--cache CACHE number of LRU-cache for RegexChecker (default: RegexChecker's default cache-size)
Redis Storage related:
--serializer {json,pickle}
type of serializer for policies stored in Redis (default: json)
```
*[Back to top](#documentation)*
### Acknowledgements
Initial code ideas of Vakt are based on
[Amazon IAM Policies](https://github.com/awsdocs/iam-user-guide/blob/master/doc_source/access_policies.md) and
[Ladon](https://github.com/ory/ladon) Policies SDK as its reference implementation.
*[Back to top](#documentation)*
### Development
To hack Vakt locally run:
```bash
$ ... # activate virtual environment w/ preferred method (optional)
$ pip install -e .[dev,mongo,sql,redis] # to install all dependencies
$ pytest -m "not integration" # to run non-integration tests with coverage report
$ pytest --cov=vakt tests/ # to get coverage report
$ pylint vakt # to check code quality with PyLint
```
To run only integration tests (for Storage adapters other than `MemoryStorage`):
```bash
$ docker run --rm -d -p 27017:27017 mongo
$ # run sql and Redis database here as well...
$ pytest -m integration
$ pytest -m sql_integration
```
Optionally you can use `make` to perform development tasks.
*[Back to top](#documentation)*
### License
The source code is licensed under Apache License Version 2.0
*[Back to top](#documentation)*
Raw data
{
"_id": null,
"home_page": "http://github.com/kolotaev/vakt",
"name": "vakt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "ACL ABAC access-control policy security authorization permission",
"author": "Egor Kolotaev",
"author_email": "ekolotaev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/45/aa/7cfe01dfd3c8322ff59e42716bd12d861b4fa4372b6b86d892933755f655/vakt-1.6.0.tar.gz",
"platform": null,
"description": "[](logo.png)\n\nAttribute-based access control (ABAC) SDK for Python.\n\n[](https://github.com/kolotaev/vakt/actions)\n[](https://app.codecov.io/gh/kolotaev/vakt/tree/master)\n[](https://badge.fury.io/py/vakt)\n[](https://raw.githubusercontent.com/kolotaev/vakt/master/LICENSE)\n\n------\n\n## Documentation\n\n- [Documentation](#documentation)\n - [Description](#description)\n - [Concepts](#concepts)\n - [Install](#install)\n - [Usage](#usage)\n - [Components](#components)\n - [Policy](#policy)\n - [Inquiry](#inquiry)\n - [Rules](#rules)\n - [Comparison-related](#comparison-related)\n - [Logic-related](#logic-related)\n - [List-related](#list-related)\n - [Network-related](#network-related)\n - [String-related](#string-related)\n - [Inquiry-related](#inquiry-related)\n - [Checker](#checker)\n - [Guard](#guard)\n - [Storage](#storage)\n - [Memory](#memory)\n - [MongoDB](#mongodb)\n - [SQL](#sql)\n - [Redis](#redis)\n - [Migration](#migration)\n - [Caching](#caching)\n - [Caching `RegexChecker`](#caching-regexchecker)\n - [Caching the entire Storage backend](#caching-the-entire-storage-backend)\n - [Caching the Guard](#caching-the-guard)\n - [JSON](#json)\n - [Logging](#logging)\n - [Audit](#audit)\n - [Milestones](#milestones)\n - [Benchmark](#benchmark)\n - [Acknowledgements](#acknowledgements)\n - [Development](#development)\n - [License](#license)\n\n\n### Description\n\nVakt is an attribute-based and policy-based access control ([ABAC](https://en.wikipedia.org/wiki/Attribute-based_access_control))\ntoolkit that is based on policies.\nABAC stands aside of RBAC and ACL models, giving you\na fine-grained control on definition of the rules that restrict an access to resources and is generally considered a\n\"next generation\" authorization model.\nIn its form Vakt resembles [IAM Policies](https://github.com/awsdocs/iam-user-guide/blob/master/doc_source/access_policies.md), but\nhas a way nicer attribute managing.\n\nSee [concepts](#concepts) section for more details.\n\n*[Back to top](#documentation)*\n\n\n### Concepts\n\nGiven you have some set of resources, you can define a number of policies that will describe access to them\nanswering the following questions:\n\n1. *What resources (resource) are being requested?*\n1. *Who is requesting the resource?*\n1. *What actions (action) are requested to be done on the asked resources?*\n1. *What are the rules that should be satisfied in the context of the request itself?*\n1. *What is resulting effect of the answer on the above questions?*\n\n\nThe overall diagram of `vakt` workflow is:\n\n[](diagram.svg)\n\n\nVakt allows you to gain:\n\n* Policy Based Access Control _(vakt is based on Policies that describe access rules, strategies to your resources)_\n* Fine-Grained Authorization _(vakt Policies give you fine-grained control over resource's, subject's, action's and context's attributes)_\n* Dynamic Authorization Management _(you can add Policies and change their attributes)_\n* Externalized Authorization Management _(you can build own external AuthZ server with vakt, see examples)_\n\n*[Back to top](#documentation)*\n\n\n### Install\n\nVakt runs on Python >= 3.6.\nPyPy implementation is supported as well.\n\nBare-bones installation with in-memory storage:\n```bash\npip install vakt\n```\n\nFor MongoDB storage:\n```bash\npip install vakt[mongo]\n```\n\nFor SQL storage:\n```bash\npip install vakt[sql]\npip install $ANY_DB_DRIVER_OF_YOUR_CHOICE_SUPPORTED_BY_SQLALCHEMY\n```\n\nFor Redis storage:\n```bash\npip install vakt[redis]\n```\nAlso see [redis-py](https://redis.readthedocs.io/en/stable/index.html) docs.\nFor example if `hiredis` is found in the system, it will be used as a faster parser.\nHowever vakt doesn't enforce this dependency.\n\n\n*[Back to top](#documentation)*\n\n\n### Usage\n\nA quick dive-in:\n\n```python\nimport vakt\nfrom vakt.rules import Eq, Any, StartsWith, And, Greater, Less\n\npolicy = vakt.Policy(\n 123456,\n actions=[Eq('fork'), Eq('clone')],\n resources=[StartsWith('repos/Google', ci=True)],\n subjects=[{'name': Any(), 'stars': And(Greater(50), Less(999))}],\n effect=vakt.ALLOW_ACCESS,\n context={'referer': Eq('https://github.com')},\n description=\"\"\"\n Allow to fork or clone any Google repository for\n users that have > 50 and < 999 stars and came from Github\n \"\"\"\n)\nstorage = vakt.MemoryStorage()\nstorage.add(policy)\nguard = vakt.Guard(storage, vakt.RulesChecker())\n\ninq = vakt.Inquiry(action='fork',\n resource='repos/google/tensorflow',\n subject={'name': 'larry', 'stars': 80},\n context={'referer': 'https://github.com'})\n\nassert guard.is_allowed(inq)\n```\n\nOr if you prefer Amazon IAM Policies style:\n\n```python\nimport vakt\nfrom vakt.rules import CIDR\n\npolicy = vakt.Policy(\n 123457,\n effect=vakt.ALLOW_ACCESS,\n subjects=[r'<[a-zA-Z]+ M[a-z]+>'],\n resources=['library:books:<.+>', 'office:magazines:<.+>'],\n actions=['read', 'get'],\n context={\n 'ip': CIDR('192.168.0.0/24'),\n },\n description=\"\"\"\n Allow all readers of the book library whose surnames start with M get and read any book or magazine,\n but only when they connect from local library's computer\n \"\"\",\n)\nstorage = vakt.MemoryStorage()\nstorage.add(policy)\nguard = vakt.Guard(storage, vakt.RegexChecker())\n\ninq = vakt.Inquiry(action='read',\n resource='library:books:Hobbit',\n subject='Jim Morrison',\n context={'ip': '192.168.0.220'})\n\nassert guard.is_allowed(inq)\n```\n\nFor more examples see [here](./examples).\n\n*[Back to top](#documentation)*\n\n### Components\n\n#### Policy\nPolicy is a main object for defining rules for accessing resources.\nThe main parts reflect questions described in [Concepts](#concepts) section:\n\n* resources - a list of resources. Answers: what is asked?\n* subjects - a list of subjects. Answers: who asks access to resources?\n* actions - a list of actions. Answers: what actions are asked to be performed on resources?\n* context - rules that should be satisfied by the given inquiry's context.\n* effect - If policy matches all the above conditions, what effect does it imply?\nCan be either `vakt.ALLOW_ACCESS` or `vakt.DENY_ACCESS`\n\nAll `resources`, `subjects` and `actions` are described with\na list containing strings, regexes, [Rules](#rules) or dictionaries of strings (attributes) to [Rules](#rules).\nEach element in list acts as logical OR. Each key in a dictionary of Rules acts as logical AND.\n`context` can be described only with a dictionary of [Rules](#rules).\n\nDepending on a way `resources`, `subjects`, `actions` are described, Policy can have either\nString-based or Rule-based type. Can be inspected by `policy.type`.\nThis enforces the use of a concrete Checker implementation. See [Checker](#checker) for more.\n\n```python\nfrom vakt import Policy, ALLOW_ACCESS\nfrom vakt.rules import CIDR, Any, Eq, NotEq, In\n\n# Rule-based policy (defined with Rules and dictionaries of Rules)\nPolicy(\n 1,\n description=\"\"\"\n Allow access to administration interface subcategories: 'panel', 'switch' if user is not\n a developer and came from local IP address.\n \"\"\",\n actions=[Any()],\n resources=[{'category': Eq('administration'), 'sub': In(['panel', 'switch'])}],\n subjects=[{'name': Any(), 'role': NotEq('developer')}],\n effect=ALLOW_ACCESS,\n context={'ip': CIDR('127.0.0.1/32')}\n)\n\n# String-based policy (defined with regular expressions)\nPolicy(\n 2,\n description=\"\"\"\n Allow all readers of the book library whose surnames start with M get and read any book or magazine,\n but only when they connect from local library's computer\n \"\"\",\n effect=ALLOW_ACCESS,\n subjects=['<[\\w]+ M[\\w]+>'],\n resources=('library:books:<.+>', 'office:magazines:<.+>'),\n actions=['<read|get>'],\n context={'ip': CIDR('192.168.2.0/24')}\n)\n```\n\nBasically you want to create some set of Policies that encompass access rules for your domain and store them for\nmaking future decisions by the [Guard](#guard) component.\n\n```python\nst = MemoryStorage()\nfor p in policies:\n st.add(p)\n```\n\nAdditionally you can create Policies with predefined effect classes:\n```python\nfrom vakt import PolicyAllow, PolicyDeny, ALLOW_ACCESS, DENY_ACCESS\n\np = PolicyAllow(1, actions=['<read|get>'], resources=['library:books:<.+>'], subjects=['<[\\w]+ M[\\w]+>'])\nassert ALLOW_ACCESS == p.effect\n\n\np = PolicyDeny(2, actions=['<read|get>'], resources=['library:books:<.+>'], subjects=['<[\\w]+ M[\\w]+>'])\nassert DENY_ACCESS == p.effect\n```\n\n*[Back to top](#documentation)*\n\n\n#### Inquiry\nInquiry is an object that serves as a mediator between Vakt and outer world request for resource access. All you need\nto do is take any kind of incoming request (REST request, SOAP, etc.) and build an `Inquiry` out of it in order to\nfeed it to Vakt. There are no concrete builders for Inquiry from various request types, since it's a very meticulous\nprocess and you have hands on control for doing it by yourself. Let's see an example:\n\n```python\nfrom vakt import Inquiry\nfrom flask import request, session\n\n...\n\n# if policies are defined on some subject's and resource's attributes with dictionaries of Rules:\ninquiry2 = Inquiry(subject={'login': request.form['username'], 'role': request.form['user_role']},\n action=request.form['action'],\n resource={'book': session.get('book'), 'chapter': request.form['chapter']},\n context={'ip': request.remote_addr})\n\n# if policies are defined with strings or regular expressions:\ninquiry = Inquiry(subject=request.form['username'],\n action=request.form['action'],\n resource=request.form['page'],\n context={'ip': request.remote_addr})\n```\n\nHere we are taking form params from Flask request and additional request information. Then we transform them\nto Inquiry. That's it.\n\nInquiry has several constructor arguments:\n\n* resource - any | dictionary of str -> any. What resource is being asked to be accessed?\n* action - any | dictionary str -> any. What is being asked to be done on the resource?\n* subject - any | dictionary str -> any. Who asks for it?\n* context - dictionary str -> any. What is the context of the request?\n\nIf you were observant enough you might have noticed that Inquiry resembles Policy, where Policy describes multiple\nvariants of resource access from the owner side and Inquiry describes an concrete access scenario from consumer side.\n\n*[Back to top](#documentation)*\n\n\n#### Rules\nRules allow you to describe conditions directly on `action`, `subject`, `resource` and `context`\nor on their attributes.\nIf at least one Rule in the Rule-set is not satisfied Inquiry is rejected by given Policy.\n\nAttaching a Rule-set to a Policy is simple. Here are some examples:\n\n```python\nfrom vakt import Policy, rules\n\nPolicy(\n ...,\n subjects=[{'name': rules.Eq('Tommy')}],\n),\n\nPolicy(\n ...,\n actions=[rules.Eq('get'), rules.Eq('list'), rules.Eq('read')],\n),\n\nPolicy(\n ...,\n context={\n 'secret': rules.string.Equal('.KIMZihH0gsrc'),\n 'ip': rules.net.CIDR('192.168.0.15/24')\n },\n)\n```\n\nThere are a number of different Rule types, see below.\n\nIf the existing Rules are not enough for you, feel free to define your [own](./examples/extending.py).\n\n##### Comparison-related\n\n| Rule | Example in Policy | Example in Inquiry | Notes |\n| ------------- |-------------|-------------|-------------|\n| Eq | `'age': Eq(40)` | `'age': 40`| |\n| NotEq | `'age': NotEq(40)` | `'age': 40`| |\n| Greater | `'height': Greater(6.2)` | `'height': 5.8`| |\n| Less | `'height': Less(6.2)` | `'height': 5.8`| |\n| GreaterOrEqual | `'stars': GreaterOrEqual(300)` | `'stars': 77`| |\n| LessOrEqual | `'stars': LessOrEqual(300)` | `'stars': 300`| |\n\n##### Logic-related\n\n| Rule | Example in Policy | Example in Inquiry | Notes |\n| ------------- |-------------|-------------|-------------|\n| Truthy | `'admin': Truthy()` | `'admin': user.is_admin()`| Evaluates on Inquiry creation |\n| Falsy | `'admin': Falsy()` | `'admin': lambda x: x.is_admin()`| Evaluates on Inquiry creation |\n| Not | `'age': Not(Greater(90))` | `'age': 40` | |\n| And | `'stars': And(Greater(50), Less(89))` | `'stars': 78` | Also, attributes in dictionary of Rules act as AND logic |\n| Or | `'stars': Or(Greater(50), Less(120), Eq(8888))` | `'stars': 78` | Also, rules in a list of, say, `actions` act as OR logic |\n| Any | `actions=[Any()]` | `action='get'`, `action='foo'` | Placeholder that fits any value |\n| Neither | `subjects=[Neither()]` | `subject='Max'`, `subject='Joe'` | Not very useful, left only as a counterpart of Any |\n\n##### List-related\n| Rule | Example in Policy | Example in Inquiry | Notes |\n| ------------- |-------------|-------------|-------------|\n| In | `'method': In('get', 'post')` | `'method': 'get'`| |\n| NotIn | `'method': NotIn('get', 'post')` | `'method': 'get'`| |\n| AllIn | `'name': AllIn('Max', 'Joe')` | `'name': ['Max', 'Joe']`| |\n| AllNotIn | `'name': AllNotIn('Max', 'Joe')` | `'name': ['Max', 'Joe']`| |\n| AnyIn | `'height': AnyIn(5.9, 7.5, 4.9)` | `'height': [7.55]`| |\n| AnyNotIn | `'height': AnyNotIn(5.9, 7.5, 4.9)` | `'height': [7.55]`| |\n\n##### Network-related\n\n| Rule | Example in Policy | Example in Inquiry | Notes |\n| ------------- |-------------|-------------|-------------|\n| CIDR | `'ip': CIDR('192.168.2.0/24')` | `'ip': 192.168.2.4`| |\n\n##### String-related\n| Rule | Example in Policy | Example in Inquiry | Notes |\n| ------------- |-------------|-------------|-------------|\n| Equal | `'name': Equal('max', ci=True)` | `'name': 'Max'`| Aliased as `StrEqual`. Use instead of `Eq` it you want string-type check and case-insensitivity |\n| PairsEqual | `'names': PairsEqual()` | `'names': ['Bob', 'Bob']`| Aliased as `StrPairsEqual` |\n| RegexMatch | `'file': RegexMatch(r'\\.rb$')` | `'file': 'test.rb'`| |\n| StartsWith | `'file': StartsWith('logs-')` | `'file': 'logs-data-101967.log'`| Supports case-insensitivity |\n| EndsWith | `'file': EndsWith('.log')` | `'file': 'logs-data-101967.log'`| Supports case-insensitivity |\n| Contains | `'file': Contains('sun')` | `'file': 'observations-sunny-days.csv'`| Supports case-insensitivity |\n\n##### Inquiry-related\n\nInquiry-related rules are useful if you want to express equality relation between inquiry elements or their attributes.\n\n| Rule | Example in Policy | Example in Inquiry | Notes |\n| ------------- |-------------|-------------|-------------|\n| SubjectMatch | `resources=[{'id': SubjectMatch()}]` | `Inquiry(subject='Max', resource={'id': 'Max'})`| Works for the whole subject value or one of its attributes |\n| ActionMatch | `subjects=[ActionMatch('id')]` | `Inquiry(subject='Max', action={'method': 'get', id': 'Max'})`| Works for the whole action value or one of its attributes |\n| ResourceMatch | `subjects=[ResourceMatch('id')]` | `Inquiry(subject='Max', resource={'res': 'book', id': 'Max'})`| Works for the whole resource value or one of its attributes |\n| SubjectEqual | `'data': SubjectEqual()` | `Inquiry(subject='Max')`| Works only for strings. Favor SubjectMatch |\n| ActionEqual | `'data': ActionEqual()` | `Inquiry(action='get')`| Works only for strings. Favor ActionMatch |\n| ResourceIn | `'data': ResourceIn()` | `Inquiry(resource='/books/')`| Works only for strings. Favor ResourceMatch |\n\n\n*[Back to top](#documentation)*\n\n\n#### Checker\nChecker allows you to check whether Policy matches Inquiry by concrete field (`subject`, `action`, etc.). It's used\ninternally by [Guard](#guard), but you should be aware of Checker types:\n\n* RulesChecker - universal type that is used to check match of Policies defined with Rules or dictionaries of Rules\n(Rule-based Policy type). It gives you the highest flexibility.\nMost of the time you will use this type of Polices and thus this type of a Checker.\nBesides, it's much more performant than RegexChecker. See [benchmark](#benchmark) for more details.\n\n```python\nfrom vakt import RulesChecker\n\nch = RulesChecker()\n# etc.\n```\n\n* RegexChecker - checks match by regex test for policies defined with strings and regexps (String-based Policy type).\nThis means that all you Policies\ncan be defined in regex syntax (but if no regex defined in Policy falls back to simple string equality test) - it\ngives you better flexibility compared to simple strings, but carries a burden of relatively slow performance.\nYou can configure a LRU cache size to adjust performance to your needs:\n\n```python\nfrom vakt import RegexChecker\n\nch = RegexChecker(2048)\nch2 = RegexChecker(512)\n# etc.\n```\nSee [benchmark](#benchmark) for more details.\n\nSyntax for description of Policy fields is:\n```\n '<foo.*>'\n 'foo<[abc]{2}>bar'\n 'foo<\\w+>'\n 'foo'\n```\nWhere `<>` are delimiters of a regular expression boundaries part. Custom Policy can redefine them by overriding\n`start_tag` and `end_tag` properties. Generally you always want to use the first variant: `<foo.*>`.\n\nDue to relatively slow performance of regular expressions execution we recommend to define your policies in\nregex syntax only when you really need it, in other cases use simple strings:\nboth will work perfectly (and now swiftly!) with RegexChecker.\n\n**NOTE. All regex checks are performed in a case-sensitive way by default.\nEven thought some storages (e.g. MemoryStorage) allow you to specify regex modifiers within the regex string, we do not translate regex modifiers to all storages (e.g. SQLStorage). Also see warning below**\n\n**WARNING. Please note, that storages have varying level of regexp support. For example,\nmost SQL databases allow to use POSIX metacharacters whereas python `re` module\nand thus MemoryStorage does not. So, while defining policies you're safe and sound\nas long as you understand how storage of your choice handles the regexps you specified.**\n\n* StringExactChecker - the most quick checker:\n```\nChecker that uses exact string equality. Case-sensitive.\nE.g. 'sun' in 'sunny' - False\n 'sun' in 'sun' - True\n```\n* StringFuzzyChecker - quick checker with some extent of flexibility:\n```\nChecker that uses fuzzy substring equality. Case-sensitive.\nE.g. 'sun' in 'sunny' - True\n 'sun' in 'sun' - True\n```\n\nNote, that some [Storage](#storage) handlers can already check if Policy fits Inquiry in\n`find_for_inquiry()` method by performing specific to that storage queries - Storage can (and generally should)\ndecide on the type of actions based on the checker class passed to [Guard](#guard) constructor\n(or to `find_for_inquiry()` directly).\n\nRegardless of the results returned by a Storage the Checker is always the last row of control\nbefore Vakt makes a decision.\n\n*[Back to top](#documentation)*\n\n\n#### Guard\nGuard component is a main entry point for Vakt to make a decision. It has one method `is_allowed` that passed an\n[Inquiry](#inquiry) gives you a boolean answer: is that Inquiry allowed or not?\n\nGuard is constructed with [Storage](#storage) and [Checker](#checker).\n\n__Policies that have String-based type won't match if RulesChecker is used and vise-versa.__\n\n```python\nst = MemoryStorage()\n# And persist all our Policies so that to start serving our library.\nfor p in policies:\n st.add(p)\n\nguard = Guard(st, RulesChecker())\n\nif guard.is_allowed(inquiry):\n return \"You've been logged-in\", 200\nelse:\n return \"Go away, you violator!\", 401\n```\n\nTo gain best performance read [Caching](#caching) section.\n\n*[Back to top](#documentation)*\n\n\n#### Storage\nStorage is a component that gives an interface for manipulating [Policies](#policy) persistence in various places.\n\nIt provides the following methods:\n```python\nadd(policy) # Store a Policy\nget(uid) # Retrieve a Policy by its ID\nget_all(limit, offset) # Retrieve all stored Policies (with pagination)\nretrieve_all(batch) # Retrieve all existing stored Policies (without pagination)\nupdate(policy) # Store an updated Policy\ndelete(uid) # Delete Policy from storage by its ID\nfind_for_inquiry(inquiry) # Retrieve Policies that match the given Inquiry\n```\n\nStorage may have various backend implementations (RDBMS, NoSQL databases, etc.), they also may vary in performance\ncharacteristics, so see [Caching](#caching) and [Benchmark](#benchmark) sections.\n\nVakt ships some Storage implementations out of the box. See below:\n\n##### Memory\nImplementation that stores Policies in memory. It's not backed by any file or something, so every restart of your\napplication will swipe out everything that was stored. Useful for testing.\n\n```python\nfrom vakt import MemoryStorage\n\nstorage = MemoryStorage()\n```\n\n##### MongoDB\nMongoDB is chosen as the most popular and widespread NO-SQL database.\n\n\n```python\nfrom pymongo import MongoClient\nfrom vakt.storage.mongo import MongoStorage\n\nclient = MongoClient('localhost', 27017)\nstorage = MongoStorage(client, 'database-name', collection='optional-collection-name')\n```\n\nDefault collection name is 'vakt_policies'.\n\nActions are the same as for any Storage that conforms interface of `vakt.storage.abc.Storage` base class.\n\nBeware that currently MongoStorage supports indexed and filtered-out `find_for_inquiry()` only for\nStringExact, StringFuzzy and Regex (since MongoDB version 4.2 and onwards) checkers.\nWhen used with the RulesChecker it simply returns all the Policies from the database.\n\n\n##### SQL\nSQL storage is backed by SQLAlchemy, thus it should support any RDBMS available for it:\nMySQL, Postgres, Oracle, MSSQL, Sqlite, etc.\n\nGiven that we support various SQL databases via SQLAlchemy, we don't specify any DB-specific drivers in the vakt\ndependencies. It's up to the user to provide a desired one. For example: `psycopg2` or `PyMySQL`.\n\nExample for MySQL.\n\n```python\nfrom sqlalchemy import create_engine\nfrom sqlalchemy.orm import sessionmaker, scoped_session\nfrom vakt.storage.sql import SQLStorage\n\nengine = create_engine('mysql://root:root@localhost/vakt_db')\nstorage = SQLStorage(scoped_session=scoped_session(sessionmaker(bind=engine)))\n\n# Don't forget to run migrations here (especially for the first time)\n...\n```\n\nBeware that currently SQLStorage supports indexed and filtered-out `find_for_inquiry()` only for\nStringExact, StringFuzzy and Regex checkers.\nWhen used with the RulesChecker it simply returns all the Policies from the database.\n\nNote that vakt focuses on testing SQLStorage functionality only for two most popular open-source databases:\nMySQL and Postgres. Other databases support may have worse performance characteristics and/or bugs.\nFeel free to report any issues.\n\n\n##### Redis\nRedis storage.\n\nRedisStorate stores all Policies in a hash whose key is the collection name and the hash'es key value pairs are\nPolicy UID -> serialized Policy representation.\n\nDefault collection name is \"vakt_policies\".\n\nYou can use different Serializers. Any custom or one of the vakt's native.\nJust pass it to the `RedisStorage` constructor.\n\nVakt is shipped with:\n- `JSONSerializer`\n- `PickleSerializer` - the fastest. Used as the default one.\n\nDue to serialization/deserialization Redis is not as fast as simple `MemoryStorage`.\nYou can run the [benchmark](#benchmark) and check performance for your use-case.\n\n```python\nfrom redis import Redis\nfrom vakt.storage.redis import RedisStorage\n\nclient = Redis('127.0.0.1', 6379)\nyield RedisStorage(client, collection='optional-policies-collection-name')\nclient.flushdb()\nclient.close()\n...\n```\n\n*[Back to top](#documentation)*\n\n\n#### Migration\n\n`vakt.migration` is a set of components that are useful from the perspective of the [Storage](#storage).\nIt's recommended to favor it over manual actions on DB schema/data\nsince it's aware of Vakt requirements to Policies data. But it's not mandatory, anyway.\nHowever it's up to a particular Storage to decide whether it needs migrations or not.\nIt consists of 3 components:\n* `Migration`\n* `MigrationSet`\n* `Migrator`\n\n`Migration` allows you to describe data modifications between versions.\nEach storage can have a number of `Migration` classes to address different releases with the order of the migration\nspecified in `order` property.\nShould be located inside particular storage module and implement `vakt.storage.migration.Migration`.\nMigration has 2 main methods (as you might guess) and 1 property:\n- `up` - runs db \"schema\" upwards\n- `down` - runs db \"schema\" downwards (rolls back the actions of `up`)\n- `order` - tells the number of the current migration in a row\n\n`MigrationSet` is a component that represents a collection of Migrations for a Storage.\nYou should define your own migration-set. It should be located inside particular storage module and implement\n`vakt.storage.migration.MigrationSet`. It has 3 methods that lest unimplemented:\n- `migrations` - should return all initialized Migration objects\n- `save_applied_number` - saves a number of a lst applied up migration in the Storage for later reference\n- `last_applied` - returns a number of a lst applied up migration from the Storage\n\n`Migrator` is an executor of a migrations. It can execute all migrations up or down, or execute a particular migration\nif `number` argument is provided.\n\nExample usage:\n\n```python\nfrom pymongo import MongoClient\nfrom vakt.storage.mongo import MongoStorage, MongoMigrationSet\nfrom vakt.storage.migration import Migrator\n\nclient = MongoClient('localhost', 27017)\nstorage = MongoStorage(client, 'database-name', collection='optional-collection-name')\n\nmigrator = Migrator(MongoMigrationSet(storage))\nmigrator.up()\n...\nmigrator.down()\n...\nmigrator.up(number=2)\n...\nmigrator.down(number=2)\n```\n\n*[Back to top](#documentation)*\n\n\n### Caching\n\nVakt has several layers of caching, that serve a single purpose: speed up policy enforcement decisions.\nIn most situations and use-cases you might want to use them all, thus they are designed not to\ninteract with each other, but rather work in tandem\n(nonetheless you are free to use any single layer alone or any combination of them).\nThat said let's look at all those layers.\n\n\n##### Caching [`RegexChecker`](#checker)\n\nIt's relevant only for `RegexChecker` and allows to cache parsing and execution of regex-defined Policies,\nwhich can be very expensive\ndue to inherently slow computational performance of regular expressions and vakt's parsing. When creating a `RegexChecker`\nyou can specify a cache size for an in-memory\n[LRU (least recently used)](https://docs.python.org/3/library/functools.html#functools.lru_cache) cache. Currently\nonly python's native LRU cache is supported.\n\n```python\n# preferably size is a power of 2\nchk = RegexChecker(cache_size=2048)\n\n# or simply\nchk = RegexChecker(2048)\n\n# or 512 by default\nchk = RegexChecker()\n```\n\n##### Caching the entire Storage backend\n\nSome vakt's Storages may be not very clever at filtering Policies at `find_for_inquiry` especially when dealing with\nRule-based policies. In this case they return the whole set of the existing policies stored in the external storage.\nNeedless to say that it makes your application very heavy IO-bound and decreases performance for large policy sets\ndrastically. See [benchmark](#benchmark) for more details and exact numbers.\n\nIn such a case you can use `EnfoldCache` that wraps your main storage (e.g. MongoStorage) into another one\n(it's meant to be some in-memory Storage). It returns you a Storage that behind the scene routes all the read-calls\n(get, get_all, find_for_inquiry, ...) to an in-memory one and all modify-calls (add, update, delete) to your main Storage (\ndon't worry, in-memory Storage is kept up-to date with the main Storage). In case a requested policy is not found in in-memory Storage\nit's considered a cache miss and a request is routed to a main Storage.\n\nAlso, in order to keep Storages in sync,\nwhen you initialize `EnfoldCache` the in-memory Storage will fetch all the existing Policies from a main one -\ntherefore be forewarned that it might take some amount of time depending on the size of a policy-set.\nOptionally you can call `populate` method after initialization, but in this case __do not ever call any modify-related methods of\nEnfoldCache'd storage before `populate()`, otherwise Storages will be in an unsynchronized state and it'll\nresult in broken `Guard` functionality.__\n\n```python\nfrom vakt import EnfoldCache, MemoryStorage, Policy, Guard, RegexChecker\nfrom vakt.storage.mongo import MongoStorage\n\nstorage = EnfoldCache(MongoStorage(...), cache=MemoryStorage())\nstorage.add(Policy(1, actions=['get']))\n\n...\n\nguard = Guard(storage, RegexChecker())\n```\n\n##### Caching the Guard\n\n`Guard.is_allowed` it the the centerpiece of vakt. Therefore it makes ultimate sense to cache it.\nAnd `create_cached_guard()` function allows you to do exactly that. You need to pass it a Storage, a Checker and a\nmaximum size of a cache. It will return you a tuple of: Guard, Storage and AllowanceCache instance:\n\n- You must do all policies operations with the returned storage\n(which is a slightly enhanced version of a Storage you provided to the function).\n- The returned Guard is a normal vakt's `Guard`, but its `is_allowed` is cached with `AllowaceCache`.\n- The returned cache is an instance of `AllowaceCache` and has a handy method `info` that provides current state of the cache.\n\nHow it works?\n\nOnly the first Inquiry will be passed to `is_allowed`, all the subsequent answers for similar Inquiries will be taken\nfrom cache. `AllowanceCache` is rather coarse-grained and if you call Storage's `add`, `update` or `delete` the whole\ncache will be invalided because the policy-set has changed. However for stable policy-sets it is a good performance boost.\n\nBy default `AllowanceCache` uses in-memory LRU cache and `maxsize` param is it's size. If for some reason it does not satisfy\nyour needs, you can pass your own implementation of a cache backend that is a subclass of\n`vakt.cache.AllowanceCacheBackend` to `create_cached_guard` as a `cache` keyword argument.\n\n```python\nguard, storage, cache = create_cached_guard(MongoStorage(...), RulesChecker(), maxsize=256)\n\np1 = Policy(1, actions=[Eq('get')], resources=[Eq('book')], subjects=[Eq('Max')], effect=ALLOW_ACCESS)\nstorage.add(p1)\n\n# Given we have some inquiries that tend to repeat\ninq1 = Inquiry(action='get', resource='book', subject='Max')\ninq2 = Inquiry(action='get', resource='book', subject='Jamey')\n\nassert guard.is_allowed(inq1)\nassert guard.is_allowed(inq1)\nassert guard.is_allowed(inq1)\nassert not guard.is_allowed(inq2)\nassert guard.is_allowed(inq1)\nassert guard.is_allowed(inq1)\n\n# You can check cache state\nassert 4 == cache.info().hits\nassert 2 == cache.info().misses\nassert 2 == cache.info().currsize\n```\n\n*[Back to top](#documentation)*\n\n\n### JSON\n\nAll Policies, Inquiries and Rules can be JSON-serialized and deserialized.\n\nFor example, for a Policy all you need is just run:\n```python\nfrom vakt.policy import Policy\n\npolicy = Policy('1')\n\njson_policy = policy.to_json()\nprint(json_policy)\n# {\"actions\": [], \"description\": null, \"effect\": \"deny\", \"uid\": \"1\",\n# \"resources\": [], \"context\": {}, \"subjects\": []}\n\npolicy = Policy.from_json(json_policy)\nprint(policy)\n# <vakt.policy.Policy object at 0x1023ca198>\n```\n\nThe same goes for Rules, Inquiries.\nAll custom classes derived from them support this functionality as well.\nIf you do not derive from Vakt's classes, but want this option, you can mix-in `vakt.util.JsonSerializer` class.\n\n```python\nfrom vakt.util import JsonSerializer\n\nclass CustomInquiry(JsonSerializer):\n pass\n```\n\n*[Back to top](#documentation)*\n\n\n### Logging\n\nVakt follows a common logging pattern for libraries:\n\nIts corresponding modules log all the events that happen but the log messages by default are handled by `NullHandler`.\nIt's up to the outer code/application to provide desired log handlers, filters, levels, etc.\n\nFor example:\n\n```python\nimport logging\n\nroot = logging.getLogger()\nroot.setLevel(logging.INFO)\nroot.addHandler(logging.StreamHandler())\n\n... # here go all the Vakt calls.\n```\n\nVakt logs can be comprehended in 2 basic levels:\n1. *Error/Exception* - informs about exceptions and errors during Vakt work.\n2. *Info* - informs about incoming inquiries, their resolution and policies responsible for this decisions\n('vakt.guard' and 'vakt.audit' streams).\n\n*[Back to top](#documentation)*\n\n\n### Audit\n\nVakt allows you to not only watch the incoming inquiries and their resolution, but also keep track of the policies\nthat were responsible for allowing or rejecting the inquiry. It's done via audit logging.\n\nAudit logging is implemented within a standard Python logging framework.\nYou can enable it by subscribing to an audit ('vakt.audit') logging \"stream\".\n\nExample of configuration in the code:\n\n```python\nimport logging\n\nlogger = logging.getLogger('vakt.audit')\nlogger.setLevel(logging.INFO)\n\nfmt = 'msg: %(message)s | effect: %(effect)s | deciders: %(deciders)s | candidates: %(candidates)s | inquiry: %(inquiry)s'\nfileHandler = logging.FileHandler('test.log')\nfileHandler.setFormatter(logging.Formatter(fmt))\nfileHandler.setLevel(logging.INFO)\nlogger.addHandler(fileHandler)\n\n... # here go all the Vakt calls.\n```\n\nVakt logs all audit records at the `INFO` level.\n\nThe formatter supports the following fields:\n\n- message - the message that tells what and why happened in the audit.\n- effect - effect that this decision has: 'allow' or 'deny'.\n- candidates - potential policies that were filtered by storage and checkers and may be responsible for the decision.\n- deciders - policies that are responsible for the final decision.\n- inquiry - the inquiry in question.\n- all the standard Python logging fields like time, level, module name, etc.\n\nThe `deciders` and `candidates` field can be logged in various ways depending on the the `audit_policies_cls`.\nIt can be passed to the `Guard` constructor.\n\nVakt has the following Audit Policies messages classes out of the box:\n\n- PoliciesNopMsg\n- PoliciesUidMsg (is the default one)\n- PoliciesDescriptionMsg\n- PoliciesCountMsg\n\nRefer to their documentation on how they represent the policies.\n\n**WARNING. Please note, that if you have Guard caching enabled, then audit records for the same subsequent inquiries won't be\nlogged because the calls are cached. However the log records from 'vakt.guard' stream will be always logged -\nthey will tell only was the inquiry allowed or not.**\n\n*[Back to top](#documentation)*\n\n\n### Milestones\n\nMost valuable features to be implemented in the order of importance:\n\n- [x] SQL Storage\n- [x] Rules that reference Inquiry data for Rule-based policies\n- [x] Caching mechanisms (for Storage and Guard)\n- [ ] YAML-based language for declarative policy definitions\n- [x] Enhanced audit logging\n- [x] Redis Storage\n\n*[Back to top](#documentation)*\n\n\n### Benchmark\n\nYou can see how much time it takes for a single Inquiry to be processed given we have a number of unique Policies in a\nStorage.\nFor [MemoryStorage](#memory) it measures the runtime of a decision-making process for all\nthe existing Policies when [Guard's](#guard) code iterates the whole list of Policies to decide if\nInquiry is allowed or not. In case of other Storages the mileage\nmay vary since they may return a smaller subset of Policies that fit the given Inquiry.\nDon't forget that most external Storages add some time penalty to perform I/O operations.\nThe runtime also depends on a Policy-type used (and thus checker): RulesChecker performs much better than RegexChecker.\n\nExample:\n\n```bash\npython3 benchmark.py --checker regex --storage memory -n 1000\n```\n\nOutput is:\n> Populating MemoryStorage with Policies<br />\n> ......................<br />\n> START BENCHMARK!<br />\n> Number of unique Policies in DB: 1,000<br />\n> Among them Policies with the same regexp pattern: 0<br />\n> Checker used: RegexChecker<br />\n> Storage used: MemoryStorage<br />\n> Number of concurrent threads: 1<br />\n> Decision for Inquiry took (mean: 0.2062 seconds. stdev: 0.0000)<br />\n> Inquiry passed the guard? False<br />\n\nScript usage:\n```\nusage: benchmark.py [-h] [-n [POLICIES_NUMBER]] [-s {mongo,memory,sql,redis}] [-d [SQL_DSN]] [-c {regex,rules,exact,fuzzy}]\n [-t [THREADS]] [--regexp] [--same SAME] [--cache CACHE] [--serializer {json,pickle}]\n\nRun vakt benchmark.\n\noptional arguments:\n -h, --help show this help message and exit\n -n [POLICIES_NUMBER], --number [POLICIES_NUMBER]\n number of policies to create in DB (default: 100000)\n -s {mongo,memory,sql,redis}, --storage {mongo,memory,sql,redis}\n type of storage (default: memory)\n -d [SQL_DSN], --dsn [SQL_DSN]\n DSN connection string for sql storage (default: sqlite:///:memory:)\n -c {regex,rules,exact,fuzzy}, --checker {regex,rules,exact,fuzzy}\n type of checker (default: regex)\n -t [THREADS], --threads [THREADS]\n number of concurrent requests (default: 1)\n\nregex policy related:\n --regexp should Policies be defined without Regex syntax? (default: True)\n --same SAME number of similar regexps in Policy\n --cache CACHE number of LRU-cache for RegexChecker (default: RegexChecker's default cache-size)\n\nRedis Storage related:\n --serializer {json,pickle}\n type of serializer for policies stored in Redis (default: json)\n```\n\n*[Back to top](#documentation)*\n\n\n### Acknowledgements\n\nInitial code ideas of Vakt are based on\n[Amazon IAM Policies](https://github.com/awsdocs/iam-user-guide/blob/master/doc_source/access_policies.md) and\n[Ladon](https://github.com/ory/ladon) Policies SDK as its reference implementation.\n\n*[Back to top](#documentation)*\n\n\n### Development\n\nTo hack Vakt locally run:\n\n```bash\n$ ... # activate virtual environment w/ preferred method (optional)\n$ pip install -e .[dev,mongo,sql,redis] # to install all dependencies\n$ pytest -m \"not integration\" # to run non-integration tests with coverage report\n$ pytest --cov=vakt tests/ # to get coverage report\n$ pylint vakt # to check code quality with PyLint\n```\n\nTo run only integration tests (for Storage adapters other than `MemoryStorage`):\n\n```bash\n$ docker run --rm -d -p 27017:27017 mongo\n$ # run sql and Redis database here as well...\n$ pytest -m integration\n$ pytest -m sql_integration\n```\n\nOptionally you can use `make` to perform development tasks.\n\n*[Back to top](#documentation)*\n\n\n### License\n\nThe source code is licensed under Apache License Version 2.0\n\n*[Back to top](#documentation)*\n",
"bugtrack_url": null,
"license": "Apache 2.0 license",
"summary": "Attribute-based access control (ABAC) SDK for Python",
"version": "1.6.0",
"split_keywords": [
"acl",
"abac",
"access-control",
"policy",
"security",
"authorization",
"permission"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "45aa7cfe01dfd3c8322ff59e42716bd12d861b4fa4372b6b86d892933755f655",
"md5": "ea0eee2b5b7b7ecc64e49eedf6d81ca0",
"sha256": "9a96a60fa061416c14d58fd0fdbaaea711abc86f82986a04cc0dfcfc1cc1bf06"
},
"downloads": -1,
"filename": "vakt-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "ea0eee2b5b7b7ecc64e49eedf6d81ca0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 89048,
"upload_time": "2023-04-12T11:18:06",
"upload_time_iso_8601": "2023-04-12T11:18:06.339953Z",
"url": "https://files.pythonhosted.org/packages/45/aa/7cfe01dfd3c8322ff59e42716bd12d861b4fa4372b6b86d892933755f655/vakt-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-12 11:18:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "kolotaev",
"github_project": "vakt",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "vakt"
}
JSON
