# What does this project solve?
It provides protection against malicious grapqhl requests (resource exhaustion).
Despite its name it can be used with graphql (pure), graphene, strawberry.
It is implemented via a custom ValidationRule,
supports error reporting and early bail out strategies as well as limits for single fields
# Installation
```sh
pip install graphene-protector
```
# Integration
## Django
This adds to django the following setting:
- GRAPHENE_PROTECTOR_DEPTH_LIMIT: max depth
- GRAPHENE_PROTECTOR_SELECTIONS_LIMIT: max selections
- GRAPHENE_PROTECTOR_COMPLEXITY_LIMIT: max (depth \* selections)
- GRAPHENE_PROTECTOR_PATH_INGORE_PATTERN: ignore fields in calculation (but still traverse them)
Integrate with:
graphene:
```python 3
# schema.py
# replace normal Schema import with:
from graphene_protector.django.graphene import Schema
schema = Schema(query=Query, mutation=Mutation)
```
and add in django settings to GRAPHENE
```python 3
GRAPHENE = {
...
"SCHEMA": "path.to.schema",
}
```
or strawberry:
```python 3
# schema.py
# replace normal Schema import with:
from graphene_protector.django.strawberry import Schema
schema = Schema(query=Query, mutation=Mutation)
```
manual way (note: import from django for including defaults from settings)
```python 3
from graphene_protector.django.graphene import Schema
# or
# from graphene_protector.django.strawberry import Schema
schema = Schema(query=Query)
result = schema.execute(query_string)
```
manual way with custom default Limits
```python 3
from graphene_protector import Limits
from graphene_protector.django.graphene import Schema
# or
# from graphene_protector.django.strawberry import Schema
schema = graphene.Schema(query=Query, limits=Limits(complexity=None))
result = schema.execute(
query_string
)
```
## Graphene & Strawberry
limits keyword with Limits object is supported.
```python 3
from graphene_protector import Limits
from graphene_protector.graphene import Schema
# or
# from graphene_protector.strawberry import Schema
schema = Schema(query=Query, limits=Limits(depth=20, selections=None, complexity=100))
result = schema.execute(query_string)
```
## pure graphql
```python 3
from graphene_protector import LimitsValidationRule
from graphql.type.schema import Schema
schema = Schema(
query=Query,
)
query_ast = parse("{ hello }")
self.assertFalse(validate(schema, query_ast, [LimitsValidationRule]))
```
or with custom defaults
```python 3
from graphene_protector import Limits, LimitsValidationRule
from graphql.type.schema import Schema
class CustomLimitsValidationRule(LimitsValidationRule):
default_limits = Limits(depth=20, selections=None, complexity=100)
schema = Schema(
query=Query,
)
query_ast = parse("{ hello }")
self.assertFalse(validate(schema, query_ast, [LimitsValidationRule]))
```
strawberry extension variant
```python 3
from graphene_protector import Limits
from graphene_protector.strawberry import CustomGrapheneProtector
from strawberry import Schema
schema = Schema(query=Query, extensions=[CustomGrapheneProtector(Limits(depth=20, selections=None, complexity=100))])
result = schema.execute(query_string)
```
or with custom defaults via Mixin
```python 3
from graphene_protector import Limits, SchemaMixin, LimitsValidationRule
from graphql.type.schema import Schema
class CustomSchema(SchemaMixin, Schema):
protector_default_limits = Limits(depth=20, selections=None, complexity=100)
schema = CustomSchema(
query=Query,
)
query_ast = parse("{ hello }")
self.assertFalse(validate(schema, query_ast, [LimitsValidationRule]))
```
strawberry variant with mixin (uses protector_per_operation_validation in contrast to the official graphene-protector strawberry schema)
```python 3
from graphene_protector import Limits, SchemaMixin, default_path_ignore_pattern
from strawberry import Schema
class CustomSchema(SchemaMixin, Schema):
protector_default_limits = Limits(depth=20, selections=None, complexity=100)
protector_path_ignore_pattern = default_path_ignore_pattern
schema = CustomSchema(query=Query)
result = schema.execute(query_string)
```
Note: for the mixin method all variables are prefixed in schema with `protector_`. Internally the `get_protector_` methods are used and mapped on the validation context. The extracted functions can be customized via the `protector_decorate_graphql_schema` method.
## Limits
A Limits object has following attributes:
- depth: max depth (default: 20, None disables feature)
- selections: max selections (default: None, None disables feature)
- complexity: max (depth subtree \* selections subtree) (default: 100, None disables feature)
- gas: accumulated gas costs (default: None, None disables feature)
- passthrough: field names specified here will be passed through regardless if specified (default: empty frozen set)
they overwrite django settings if specified.
## decorating single fields
Sometimes single fields should have different limits:
```python
from graphene_protector import Limits
person1 = Limits(depth=10)(graphene.Field(Person))
```
Limits are passthroughs for missing parameters
There is also a novel technique named gas: you can assign a field a static value or dynamically calculate it for the field
The decorator is called gas_usage
```python
from graphene_protector import gas_usage
person1 = gas_usage(10)(graphene.Field(Person))
# dynamic way:
person2 = gas_usage(lambda **kwargs: 10)(graphene.Field(Person))
```
see tests for more examples
## one-time disable limit checks
to disable checks for one operation use check_limits=False (works for:
execute, execute_async (if available), subscribe (if available)):
```python 3
from graphene_protector import Limits
from graphene_protector.graphene import Schema
schema = Schema(query=Query, limits=Limits(depth=20, selections=None, complexity=100))
result = schema.execute(query_string, check_limits=False)
```
Usefull for debugging or working around errors
# Path ignoring
This is a feature for ignoring some path parts in calculation but still traversing them.
It is useful for e.g. relay which inflates the depth significant and can cause problems with complexity
Currently it is set to `edges/node$` which reduces the depth of connections by one.
If you want to ignore all children on a path then remove $ but be warned: it can be a long path and it is still traversed.
The path the regex matches agains is composed like this: `fieldname/subfields/...`.
Other examples are:
- `node$|id$` for ignoring id fields in selection/complexity count and reducing the depth by 1 when seeing a node field
- `page_info|pageInfo` for ignoring page info in calculation (Note: you need only one, in case auto_snakecase=True only `pageInfo`)
Note: items prefixed with `__` (internal names) are always ignored and not traversed.
Note: if auto_snakecase is True, the path components are by default camel cased (overwritable via explicit `camelcase_path`)
Note: gas is excluded from path ignoring
# Gas
Gas should be a positive integer. Negative integers are possible but
the evaulation is stopped whenever the counter is above the limit so this is not reliable
The gas usage is annotated with the gas_usage decorator. A function can be passed
which receives the following keyword arguments:
- schema_field
- fieldname
- parent (parent of schema_field)
- graphql_path
# full validation
On the validation rule the validation is stopped by default when an error is found
This default can be overwritten and it is modified for the django code pathes.
Whenever DEBUG is active a full validation happens, otherwise the shortcut is used.
See the source-code how to change your schema to have a custom hook for deciding if a full validation is done.
In addition the `path_ignore_pattern` and `limits` attributes can be also changed dynamically.
# hooks
The validation rule uses some `protector_` prefixed methods from the schema.
With this you can customize the default behaviour.
It is used by the django mixin to read the settings (see django) and to react on DEBUG with full_validation
# Development
I am open for new ideas.
If you want some new or better algorithms integrated just make a PR
## Internals
Path ignoring is ignored for the gas calculation (gas is always explicit). Therefor there is no way to stop when an open path was found (all children are ignored).
This project uses a "stack free" recursive approach. Instead of calling recursively, generators are used to remember the position and to continue.
Note: graphql itself will fail because they are not using a stack free approach. For graphql there was a limit around 200 depth. The graphql tree cannot be constructed so there is no way to evaluate this.
# related projects:
- secure-graphene: lacks django integration, some features and has a not so easy findable name.
But I accept: it is the "not invented here"-syndrome
- cost specs: https://ibm.github.io/graphql-specs/cost-spec.html
looks nice but very hard to implement. Handling costs at client and server side synchronously is complicated.
Also the costs are baked into the schema, which crosses the boundary between static and dynamic
# TODO
- manually construct the graphql tree for tests for check_resource_usages
- fill RessourceLimits (graphql errors) with details like the field where the limit was reached
- improve documentation
- keep an eye on the performance impact of the new path regex checking
- add tests for auto_snakecase and camelcase_path
- skip tests in case settings are not matching
Raw data
{
"_id": null,
"home_page": "https://github.com/devkral/graphene-protector",
"name": "graphene-protector",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4",
"maintainer_email": "",
"keywords": "graphql,strawberry,extension",
"author": "alex",
"author_email": "devkral@web.de",
"download_url": "https://files.pythonhosted.org/packages/c8/cc/0321fc10296908e7ace52e86857693601c40dd066abb5c395cda9545e384/graphene_protector-0.12.1.tar.gz",
"platform": null,
"description": "# What does this project solve?\n\nIt provides protection against malicious grapqhl requests (resource exhaustion).\nDespite its name it can be used with graphql (pure), graphene, strawberry.\nIt is implemented via a custom ValidationRule,\nsupports error reporting and early bail out strategies as well as limits for single fields\n\n# Installation\n\n```sh\npip install graphene-protector\n```\n\n# Integration\n\n## Django\n\nThis adds to django the following setting:\n\n- GRAPHENE_PROTECTOR_DEPTH_LIMIT: max depth\n- GRAPHENE_PROTECTOR_SELECTIONS_LIMIT: max selections\n- GRAPHENE_PROTECTOR_COMPLEXITY_LIMIT: max (depth \\* selections)\n- GRAPHENE_PROTECTOR_PATH_INGORE_PATTERN: ignore fields in calculation (but still traverse them)\n\nIntegrate with:\n\ngraphene:\n\n```python 3\n# schema.py\n# replace normal Schema import with:\nfrom graphene_protector.django.graphene import Schema\nschema = Schema(query=Query, mutation=Mutation)\n```\n\nand add in django settings to GRAPHENE\n\n```python 3\n\nGRAPHENE = {\n ...\n \"SCHEMA\": \"path.to.schema\",\n}\n```\n\nor strawberry:\n\n```python 3\n# schema.py\n# replace normal Schema import with:\nfrom graphene_protector.django.strawberry import Schema\nschema = Schema(query=Query, mutation=Mutation)\n```\n\nmanual way (note: import from django for including defaults from settings)\n\n```python 3\nfrom graphene_protector.django.graphene import Schema\n# or\n# from graphene_protector.django.strawberry import Schema\nschema = Schema(query=Query)\nresult = schema.execute(query_string)\n```\n\nmanual way with custom default Limits\n\n```python 3\nfrom graphene_protector import Limits\nfrom graphene_protector.django.graphene import Schema\n# or\n# from graphene_protector.django.strawberry import Schema\nschema = graphene.Schema(query=Query, limits=Limits(complexity=None))\nresult = schema.execute(\n query_string\n)\n\n```\n\n## Graphene & Strawberry\n\nlimits keyword with Limits object is supported.\n\n```python 3\nfrom graphene_protector import Limits\nfrom graphene_protector.graphene import Schema\n# or\n# from graphene_protector.strawberry import Schema\nschema = Schema(query=Query, limits=Limits(depth=20, selections=None, complexity=100))\nresult = schema.execute(query_string)\n```\n\n## pure graphql\n\n```python 3\n\nfrom graphene_protector import LimitsValidationRule\nfrom graphql.type.schema import Schema\nschema = Schema(\n query=Query,\n)\nquery_ast = parse(\"{ hello }\")\nself.assertFalse(validate(schema, query_ast, [LimitsValidationRule]))\n\n```\n\nor with custom defaults\n\n```python 3\n\nfrom graphene_protector import Limits, LimitsValidationRule\nfrom graphql.type.schema import Schema\n\nclass CustomLimitsValidationRule(LimitsValidationRule):\n default_limits = Limits(depth=20, selections=None, complexity=100)\n\nschema = Schema(\n query=Query,\n)\nquery_ast = parse(\"{ hello }\")\nself.assertFalse(validate(schema, query_ast, [LimitsValidationRule]))\n\n```\n\nstrawberry extension variant\n\n```python 3\nfrom graphene_protector import Limits\nfrom graphene_protector.strawberry import CustomGrapheneProtector\nfrom strawberry import Schema\nschema = Schema(query=Query, extensions=[CustomGrapheneProtector(Limits(depth=20, selections=None, complexity=100))])\nresult = schema.execute(query_string)\n```\n\nor with custom defaults via Mixin\n\n```python 3\n\nfrom graphene_protector import Limits, SchemaMixin, LimitsValidationRule\nfrom graphql.type.schema import Schema\n\nclass CustomSchema(SchemaMixin, Schema):\n protector_default_limits = Limits(depth=20, selections=None, complexity=100)\n\nschema = CustomSchema(\n query=Query,\n)\nquery_ast = parse(\"{ hello }\")\nself.assertFalse(validate(schema, query_ast, [LimitsValidationRule]))\n\n```\n\nstrawberry variant with mixin (uses protector_per_operation_validation in contrast to the official graphene-protector strawberry schema)\n\n```python 3\nfrom graphene_protector import Limits, SchemaMixin, default_path_ignore_pattern\nfrom strawberry import Schema\n\nclass CustomSchema(SchemaMixin, Schema):\n protector_default_limits = Limits(depth=20, selections=None, complexity=100)\n protector_path_ignore_pattern = default_path_ignore_pattern\n\nschema = CustomSchema(query=Query)\nresult = schema.execute(query_string)\n```\n\nNote: for the mixin method all variables are prefixed in schema with `protector_`. Internally the `get_protector_` methods are used and mapped on the validation context. The extracted functions can be customized via the `protector_decorate_graphql_schema` method.\n\n## Limits\n\nA Limits object has following attributes:\n\n- depth: max depth (default: 20, None disables feature)\n- selections: max selections (default: None, None disables feature)\n- complexity: max (depth subtree \\* selections subtree) (default: 100, None disables feature)\n- gas: accumulated gas costs (default: None, None disables feature)\n- passthrough: field names specified here will be passed through regardless if specified (default: empty frozen set)\n\nthey overwrite django settings if specified.\n\n## decorating single fields\n\nSometimes single fields should have different limits:\n\n```python\nfrom graphene_protector import Limits\nperson1 = Limits(depth=10)(graphene.Field(Person))\n```\n\nLimits are passthroughs for missing parameters\n\nThere is also a novel technique named gas: you can assign a field a static value or dynamically calculate it for the field\n\nThe decorator is called gas_usage\n\n```python\nfrom graphene_protector import gas_usage\nperson1 = gas_usage(10)(graphene.Field(Person))\n# dynamic way:\nperson2 = gas_usage(lambda **kwargs: 10)(graphene.Field(Person))\n\n```\n\nsee tests for more examples\n\n## one-time disable limit checks\n\nto disable checks for one operation use check_limits=False (works for:\nexecute, execute_async (if available), subscribe (if available)):\n\n```python 3\nfrom graphene_protector import Limits\nfrom graphene_protector.graphene import Schema\nschema = Schema(query=Query, limits=Limits(depth=20, selections=None, complexity=100))\nresult = schema.execute(query_string, check_limits=False)\n```\n\nUsefull for debugging or working around errors\n\n# Path ignoring\n\nThis is a feature for ignoring some path parts in calculation but still traversing them.\nIt is useful for e.g. relay which inflates the depth significant and can cause problems with complexity\nCurrently it is set to `edges/node$` which reduces the depth of connections by one.\nIf you want to ignore all children on a path then remove $ but be warned: it can be a long path and it is still traversed.\nThe path the regex matches agains is composed like this: `fieldname/subfields/...`.\n\nOther examples are:\n\n- `node$|id$` for ignoring id fields in selection/complexity count and reducing the depth by 1 when seeing a node field\n- `page_info|pageInfo` for ignoring page info in calculation (Note: you need only one, in case auto_snakecase=True only `pageInfo`)\n\nNote: items prefixed with `__` (internal names) are always ignored and not traversed.\n\nNote: if auto_snakecase is True, the path components are by default camel cased (overwritable via explicit `camelcase_path`)\n\nNote: gas is excluded from path ignoring\n\n# Gas\n\nGas should be a positive integer. Negative integers are possible but\nthe evaulation is stopped whenever the counter is above the limit so this is not reliable\n\nThe gas usage is annotated with the gas_usage decorator. A function can be passed\nwhich receives the following keyword arguments:\n\n- schema_field\n- fieldname\n- parent (parent of schema_field)\n- graphql_path\n\n# full validation\n\nOn the validation rule the validation is stopped by default when an error is found\nThis default can be overwritten and it is modified for the django code pathes.\nWhenever DEBUG is active a full validation happens, otherwise the shortcut is used.\nSee the source-code how to change your schema to have a custom hook for deciding if a full validation is done.\nIn addition the `path_ignore_pattern` and `limits` attributes can be also changed dynamically.\n\n# hooks\n\nThe validation rule uses some `protector_` prefixed methods from the schema.\nWith this you can customize the default behaviour.\nIt is used by the django mixin to read the settings (see django) and to react on DEBUG with full_validation\n\n# Development\n\nI am open for new ideas.\nIf you want some new or better algorithms integrated just make a PR\n\n## Internals\n\nPath ignoring is ignored for the gas calculation (gas is always explicit). Therefor there is no way to stop when an open path was found (all children are ignored).\n\nThis project uses a \"stack free\" recursive approach. Instead of calling recursively, generators are used to remember the position and to continue.\n\nNote: graphql itself will fail because they are not using a stack free approach. For graphql there was a limit around 200 depth. The graphql tree cannot be constructed so there is no way to evaluate this.\n\n# related projects:\n\n- secure-graphene: lacks django integration, some features and has a not so easy findable name.\n But I accept: it is the \"not invented here\"-syndrome\n- cost specs: https://ibm.github.io/graphql-specs/cost-spec.html\n looks nice but very hard to implement. Handling costs at client and server side synchronously is complicated.\n Also the costs are baked into the schema, which crosses the boundary between static and dynamic\n\n# TODO\n\n- manually construct the graphql tree for tests for check_resource_usages\n- fill RessourceLimits (graphql errors) with details like the field where the limit was reached\n- improve documentation\n- keep an eye on the performance impact of the new path regex checking\n- add tests for auto_snakecase and camelcase_path\n- skip tests in case settings are not matching\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Protects graphene, graphql or strawberry against malicious queries",
"version": "0.12.1",
"project_urls": {
"Homepage": "https://github.com/devkral/graphene-protector",
"Repository": "https://github.com/devkral/graphene-protector"
},
"split_keywords": [
"graphql",
"strawberry",
"extension"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8e36fafe40d33b64580726420d0b840a96f53ef44b415f50190b3ce53be8b651",
"md5": "6c3246f0954c38b620e2041ab60f6fa2",
"sha256": "6bf5a92e075df5e3dc500c21a67b8afef443a2132c1bb27f732560c9bc093555"
},
"downloads": -1,
"filename": "graphene_protector-0.12.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c3246f0954c38b620e2041ab60f6fa2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4",
"size": 14130,
"upload_time": "2024-03-17T07:57:19",
"upload_time_iso_8601": "2024-03-17T07:57:19.409370Z",
"url": "https://files.pythonhosted.org/packages/8e/36/fafe40d33b64580726420d0b840a96f53ef44b415f50190b3ce53be8b651/graphene_protector-0.12.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c8cc0321fc10296908e7ace52e86857693601c40dd066abb5c395cda9545e384",
"md5": "31655f824436ea07fa21b92939f426b7",
"sha256": "f3426401fc9e68382e019d9fad00f95bca68c1205ce297b912d41160e80d3c7a"
},
"downloads": -1,
"filename": "graphene_protector-0.12.1.tar.gz",
"has_sig": false,
"md5_digest": "31655f824436ea07fa21b92939f426b7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4",
"size": 14787,
"upload_time": "2024-03-17T07:57:21",
"upload_time_iso_8601": "2024-03-17T07:57:21.445682Z",
"url": "https://files.pythonhosted.org/packages/c8/cc/0321fc10296908e7ace52e86857693601c40dd066abb5c395cda9545e384/graphene_protector-0.12.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-17 07:57:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "devkral",
"github_project": "graphene-protector",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "graphene-protector"
}
JSON
