Welcome to Py-ABAC’s documentation!¶

Py-ABAC is an attribute-based access control (ABAC) toolkit based on policies. ABAC gives 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. The design of py-ABAC stems from the XACML standard, and the ABAC python SDK Vakt.

See Concepts for more detail.

Installation¶

PyABAC runs on Python >= 3.5. PyPy implementation is supported as well.

To install basic package run the following:

pip install py-abac

With the basic package the in-memory policy storage backend can be used. For the other persistent backends run:

# MongoDB backend
pip install py-abac[mongo]

# SQL backend
pip install py-abac[sql]

Quick Example¶

The following code shows a quick example usage of Py-ABAC:

from pymongo import MongoClient
from py_abac import PDP, Policy, Request
from py_abac.storage.mongo import MongoStorage

# Policy definition in JSON
policy_json = {
    "uid": "1",
    "description": "Max and Nina are allowed to create, delete, get any "
                   "resources only if the client IP matches.",
    "effect": "allow",
    "rules": {
        "subject": [{"$.name": {"condition": "Equals", "value": "Max"}},
                    {"$.name": {"condition": "Equals", "value": "Nina"}}],
        "resource": {"$.name": {"condition": "RegexMatch", "value": ".*"}},
        "action": [{"$.method": {"condition": "Equals", "value": "create"}},
                   {"$.method": {"condition": "Equals", "value": "delete"}},
                   {"$.method": {"condition": "Equals", "value": "get"}}],
        "context": {"$.ip": {"condition": "CIDR", "value": "127.0.0.1/32"}}
    },
    "targets": {},
    "priority": 0
}
# Parse JSON and create policy object
policy = Policy.from_json(policy_json)

# Setup policy storage
client = MongoClient()
storage = MongoStorage(client)
# Add policy to storage
storage.add(policy)

# Create policy decision point
pdp = PDP(storage)

# A sample access request JSON
request_json = {
    "subject": {
        "id": "",
        "attributes": {"name": "Max"}
    },
    "resource": {
        "id": "",
        "attributes": {"name": "myrn:example.com:resource:123"}
    },
    "action": {
        "id": "",
        "attributes": {"method": "get"}
    },
    "context": {
        "ip": "127.0.0.1"
    }
}
# Parse JSON and create access request object
request = Request.from_json(request_json)

# Check if access request is allowed. Evaluates to True since
# Max is allowed to get any resource when client IP matches.
assert pdp.is_allowed(request)

Documentation¶

py_abac

License

Logging¶

Py-ABAC 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:

import logging

root = logging.getLogger()
root.setLevel(logging.INFO)
root.addHandler(logging.StreamHandler())

... # here go all the py_abac calls.

Acknowledgements¶

The conceptual and implementation design of Py-ABAC stems from the XACML standard and the ABAC python SDK Vakt.

Development¶

Py-ABAC requires a few backend databases like MongoDB, MySQL, etc for testing and development. For convenience a docker-compose <https://github.com/ketgo/py-abac/blob/master/tests/docker-compose.yml>_ file is provided in the test folder to spawn up the required infrastructure. Just run:

$ cd tests
$ docker-compose up -d      # this spawns up all the databases.
$ cd ..     # returns to the root repo folder

To hack Py-ABAC locally run:

$ pip install -e .[dev]         # to install all dependencies
$ docker run --rm -d -p 27017:27017 mongo           # Run mongodb server on docker
$ pytest --cov=py_abac tests/           # to get coverage report
$ pylint py_abac            # to check code quality with PyLint
$ bandit py_abac            # to check code security with Bandit

Optionally you can use make to perform development tasks.