PyPermission 0.1.1

Description:

PyPermission 0.1.1

A role-based access control (RBAC) permission library for python.












WARNING: ALPHA VERSION
This is a prototype. APIs will be subjects to breaking changes! Existing APIs are not battle tested
and might exhibit unexpected behavior!
Features

NIST Model for RBAC: https://doi.org/10.1145/344287.344301

Level 1: Flat (Missing method)
Level 2a: Hierarchical
Level 3a: Constrained (TODO)
Level 4a: Symmetric (TODO)


Permissions with hierarchical ordering
Permissions with string payloads
Persistency backends

SQLAlchemy
JSON + YAML save files


Subject permission assignment (UBAC oriented)
Online Documentation (TODO, is incomplete and incorrect)

Installation
pip
PyPermission can be installed directly from the PyPI repositories.
JSON persistency backend
pip install PyPermission

SQLAlchemy persistency backend
pip install PyPermission[sqlalchemy]

JSON + YAML persistency backend
pip install PyPermission[yaml]

Editable installation for developers
Install PyPermission from the git
repository with:
git clone https://gitlab.com/DigonIO/PyPermission.git
cd PyPermission
python -m venv venv # optional
source ./venv/bin/activate # optional
pip install -e .[dev]

Example: How to RBAC
Import all required objects. Here we will choose the authority with the JSON persistency backend.
from pypermission import PermissionNode
from pypermission.yaml import SerialAuthority

Define an authority with some permission nodes:
class Nodes(PermissionNode):
CHAT_ = "chat.*" # parent
CHAT_GLOBAL = "chat.global" # leaf
CHAT_MODERATOR = "chat.moderator" # leaf
TICKET_ = "ticket.*" # parent
TICKET_OPEN = "ticket.open" # leaf
TICKET_CLOSE_ = "ticket.close.*" # parent
TICKET_CLOSE_OWN = "ticket.close.own" # leaf
TICKET_CLOSE_ALL = "ticket.close.all" # leaf
TICKET_ASSIGN = "ticket.assign" # leaf

auth = SerialAuthority(nodes=Nodes)

The following file save_file.yaml defines a RBAC setup. Alice is
a member of the user and moderator role, while Bob is assigned only to the user role:
roles:
moderator:
permission_nodes:
- chat.*
- ticket.*
member_subjects:
- Alice
user:
permission_nodes:
- chat.global
- ticket.open
- ticket.close.own
member_subjects:
- Alice
- Bob
subjects:
Alice: {}
Bob: {}

auth.load_file(path="save_file.yaml")

Now check if a subject has a desired permission.
>>> auth.subject_has_permission(sid="Bob", node=Nodes.CHAT_GLOBAL)
True

>>> auth.subject_has_permission(sid="Alice", node=Nodes.CHAT_MODERATOR)
True

>>> auth.subject_has_permission(sid="Bob", node=Nodes.TICKET_OPEN)
True

>>> auth.subject_has_permission(sid="Alice", node=Nodes.TICKET_CLOSE_ALL)
True

Documentation
The API documentation can either be viewed
online
or generated using Sphinx with numpydoc
formatting. To build, run:
sphinx-build -b html docs/ docs/_build/html

Testing
Testing is done using pytest. With
pytest-cov and
coverage a report for the test coverage can be generated:
pytest --cov=src/ tests/
coverage html

To test the examples in the documentation run:
pytest docs/

License
This free and open source software (FOSS) is published under the LGPLv3 license.