Policy Shard

PolicyShards are a simplified representation of policies.

class PolicyShard(effect, effective_action, effective_resource, effective_principal, effective_condition=None)

A PolicyShard is part of a policy broken down in such a way that it can be deduplicated and collapsed.

Parameters
Return type

None

class Config

Pydantic Config.

json_encoders = {<class 'policyglass.action.EffectiveAction'>: <function PolicyShard.Config.<lambda>>, <class 'policyglass.resource.EffectiveResource'>: <function PolicyShard.Config.<lambda>>, <class 'policyglass.principal.EffectivePrincipal'>: <function PolicyShard.Config.<lambda>>}
__init__(effect, effective_action, effective_resource, effective_principal, effective_condition=None)

Initialize a PolicyShard object.

Parameters
  • effect (str) – ‘Allow’ or ‘Deny’

  • effective_action (policyglass.effective_arp.EffectiveARP[policyglass.action.Action]) – The EffectiveAction that this PolicyShard allows or denies

  • effective_resource (policyglass.effective_arp.EffectiveARP[policyglass.resource.Resource]) – The EffectiveResource that this PolicyShard allows or denies

  • effective_principal (policyglass.effective_arp.EffectiveARP[policyglass.principal.Principal]) – The EffectivePrincipal that this PolicyShard allows or denies

  • effective_condition (Optional[policyglass.condition.EffectiveCondition]) – The EffectiveCondition that needs to be met for this PolicyShard to apply

Return type

None

dict(*args, **kwargs)

Convert instance to dict representation of it.

Parameters
  • *args – Arguments to Pydantic dict method.

  • **kwargs – Arguments to Pydantic dict method.

Return type

Dict[str, Any]

Overridden from BaseModel so that when converting conditions to dict they don’t suffer from being unhashable when placed in a set.

difference(other, dedupe_result=True)

Calculate the difference between this and another object of the same type.

Effectively subtracts the inclusions of other from self. This is useful when applying denies (other) to allows (self).

Parameters
  • other (object) – The object to subtract from this one.

  • dedupe_result (bool) – Whether to deduplicate the resulting PolicyShards or not. Setting this to False will lead to many duplicates.

Raises

ValueError – If other is not the same type as this object.

Return type

List[policyglass.policy_shard.PolicyShard]

effect: str
effective_action: policyglass.effective_arp.EffectiveARP[policyglass.action.Action]
effective_condition: policyglass.condition.EffectiveCondition
effective_principal: policyglass.effective_arp.EffectiveARP[policyglass.principal.Principal]
effective_resource: policyglass.effective_arp.EffectiveARP[policyglass.resource.Resource]
property explain: str

Return a plain English representation of the policy shard.

Example

Simple PolicyShard explain.

>>> from policyglass import Policy
>>> policy = Policy(**{"Statement": [{"Effect": "Allow", "Action": "s3:*"}]})
>>> print([shard.explain for shard in policy.policy_shards])
['Allow action s3:* on resource * with principal AWS *.']
intersection(other)

Calculate the intersection between this object and another object of the same type.

Parameters

other (object) – The object to intersect with this one.

Raises

ValueError – if other is not the same type as this object.

Return type

Optional[policyglass.policy_shard.PolicyShard]

issubset(other)

Whether this object contains all the elements of another object (i.e. is a subset of the other object).

Conditions:

If both PolicyShards have conditions but are otherwise identical, self will be a subset of other if the other’s conditions are are a subset of self’s as this means that self is more restrictive and therefore carves out a subset of possiblilites in comparison with other.

Parameters

other (object) – The object to determine if our object contains.

Raises

ValueError – If the other object is not of the same type as this object.

Return type

bool

union(other)

Combine this object with another object of the same type.

Parameters

other (object) – The object to combine with this one.

Raises

ValueError – If other is not the same type as this object.

Return type

List[policyglass.policy_shard.PolicyShard]

dedupe_policy_shard_subsets(shards, check_reverse=True)

Dedupe policy shards that are subsets of each other.

Parameters
  • shards (Iterable[policyglass.policy_shard.PolicyShard]) – The shards to deduplicate.

  • check_reverse (bool) – Whether you want to check these shards in reverse as well (only disabled when alling itself).

Return type

List[policyglass.policy_shard.PolicyShard]

dedupe_policy_shards(shards, check_reverse=True)

Dedupe policy shards that are subsets of each other and remove intersections.

Parameters
  • shards (Iterable[policyglass.policy_shard.PolicyShard]) – The shards to deduplicate.

  • check_reverse (bool) – Whether you want to check these shards in reverse as well (only disabled when calling itself).

Return type

List[policyglass.policy_shard.PolicyShard]

explain_policy_shards(shards, language='en')

Return a list of string explanations for a given list of PolicyShards.

Example

How to get the effective permissions of a policy as a plain English explanation.

>>> from policyglass import Policy, policy_shards_effect, explain_policy_shards
>>> policy = Policy(
...     **{
...         "Version": "2012-10-17",
...         "Statement": [
...             {
...                 "Effect": "Allow",
...                 "Action": ["s3:*"],
...                 "Resource": "*",
...             },
...             {
...                 "Effect": "Deny",
...                 "Action": ["s3:Get*"],
...                 "Resource": "*",
...             },
...         ],
...     }
... )
>>> explain_policy_shards(policy_shards_effect(policy.policy_shards))
['Allow action s3:* (except for s3:Get*) on resource * with principal AWS *.']
Parameters
Raises

NotImplementedError – When an unsupported language is requested.

Return type

List[str]

policy_shards_effect(shards)

Calculate the effect of merging allow and deny shards together.

Example

How to get the effective permissions of a policy as PolicyShard objects.

>>> from policyglass import Policy, policy_shards_effect, explain_policy_shards
>>> policy = Policy(
...     **{
...         "Version": "2012-10-17",
...         "Statement": [
...             {
...                 "Effect": "Allow",
...                 "Action": ["s3:*"],
...                 "Resource": "*",
...             },
...             {
...                 "Effect": "Deny",
...                 "Action": ["s3:Get*"],
...                 "Resource": "*",
...             },
...         ],
...     }
... )
>>> policy_shards = policy.policy_shards
>>> policy_shards_effect(policy_shards)
[PolicyShard(effect='Allow',
    effective_action=EffectiveAction(inclusion=Action('s3:*'),
        exclusions=frozenset({Action('s3:Get*')})),
    effective_resource=EffectiveResource(inclusion=Resource('*'),
        exclusions=frozenset()),
    effective_principal=EffectivePrincipal(inclusion=Principal(type='AWS', value='*'),
        exclusions=frozenset()),
    effective_condition=EffectiveCondition(inclusions=frozenset(),
        exclusions=frozenset()))]
Parameters

shards (List[policyglass.policy_shard.PolicyShard]) – The shards to caclulate the effect of.

Return type

List[policyglass.policy_shard.PolicyShard]

policy_shards_to_json(shards, exclude_defaults=False, **kwargs)

Convert a list of PolicyShard objects to JSON.

Example

How to get the effective permissions of a policy as json.

>>> from policyglass import Policy, policy_shards_effect, policy_shards_to_json
>>> policy = Policy(
...     **{
...         "Version": "2012-10-17",
...         "Statement": [
...             {
...                 "Effect": "Allow",
...                 "Action": ["s3:*"],
...                 "Resource": "*",
...             },
...             {
...                 "Effect": "Deny",
...                 "Action": ["s3:Get*"],
...                 "Resource": "*",
...             },
...         ],
...     }
... )
>>> policy_shards = policy.policy_shards
>>> output = policy_shards_to_json(
...     policy_shards_effect(policy_shards),
...     indent=2,
...     exclude_defaults=True
... )
>>> print(output)
[
    {
        "effective_action": {
            "inclusion": "s3:*",
            "exclusions": [
                "s3:Get*"
            ]
        },
        "effective_resource": {
            "inclusion": "*"
        },
        "effective_principal": {
            "inclusion": {
                "type": "AWS",
                "value": "*"
            }
        }
    }
]
Parameters
Return type

str