Add security best practices in documentation

docs/continuous-security-testing.md

@@ -0,0 +1,27 @@
+---
+id: continuous-security-testing
+title: Continuous security testing
+sidebar_label: Continuous security testing
+---
+
+## Continuous security testing
+
+One of the best way to stop wondering about security for your API, you might want to setup security scans in your continuous delivery tools.
+
+The same way applications are now automatically deployed by CI/CD pipelines, you can bullet-proof your GraphQL application before it even reaches a production environment.
+
+## CI/CD security testing tools
+
+### [graphql.security](https://graphql.security/)
+
+`graphql.security` is a *free*, *quick* graphql security testing tool, allowing you to quickly assess the most common vulnerabilities in your application.
+
+### [Escape](https://escape.tech/)
+
+Escape is a GraphQL security SaaS platform, running a DAST (dynamic application security testing) tool on your api directly from a CI/CD environment.
+
+This platform can be [easily integrated into your existing CI/CD pipeline](https://escape.tech/docs/ci-cd/) (Github Actions, Gitlab CIs, etc.), enabling you to set it up easily.
+
+Security alerts will be directly reported in your CI/CD platform, making it faster than ever to address them.
+
+[See how to setup Escape for your GraphQL application](https://escape.tech/docs/introduction)

docs/disabling-stack-traces.md

@@ -0,0 +1,72 @@
+---
+id: disabling-stack-traces
+title: Disabling stack traces
+sidebar_label: Disabling stack traces
+---
+
+## Stack traces
+
+### Description
+
+The Ariadne engine includes a debug mode which attaches stacktraces and error properties to GraphQL requests.
+
+In order to protect against engine targeted attacks and ensure that credentials do not leak in stacktraces, it is essential to disable debug mode in production.
+
+The following presents an error occuring when the server tries to fetch data from the database. This response exposes the **complete database URL.**
+
+```json
+{
+ "data": {
+ "me": null
+ },
+ "errors": [
+ {
+ "message": "no such column: \"username\"",
+ "locations": [
+ {
+ "line": 1,
+ "column": 16
+ }
+ ],
+ "path": [
+ "request0"
+ ],
+ "extensions": {
+ "exception": {
+ "stacktrace": [
+ "Traceback (most recent call last):",
+ " File \"/root/.cache/pypoetry/virtualenvs/gontoz-9TtSrW0h-py3.11/lib/python3.11/site-packages/graphql/execution/execute.py\", line 528, in await_result",
+ " return_type, field_nodes, info, path, await result",
+ " ^^^^^^^^^^^^",
+ " File \"/root/.cache/pypoetry/virtualenvs/gontoz-9TtSrW0h-py3.11/lib/python3.11/site-packages/ariadne/utils.py\", line 70, in async_wrapper",
+ " return await func(*args, **convert_to_snake_case(kwargs))",
+ " ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^",
+ " File \"/app/gontoz/queries.py\", line 100, in resolve_transactions",
+ " return database.get_transaction_from_vuln(",
+ " ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^",
+ " File \"/app/gontoz/database_manager/main.py\", line 274, in get_transaction_from_vuln",
+ " for transaction in self.cur.execute(query).fetchall():",
+ " ^^^^^^^^^^^^^^^^^^^^^^^",
+ "sqlite3.OperationalError: no such column: None"
+ ],
+ "context": {
+ "self": "<myapp.datab...x7f502112f890>",
+ "user_id": "None",
+ "query": "'SELECT * FRO...user_to = 125'",
+ "transactions": "[]",
+ "database_url": "postgresql://user:pass@db:5432/db",
+ }
+ }
+ }
+ }
+ ]
+}
+```
+
+### Hiding stack traces
+
+When running an application in production, make sure the debug mode is not enabled.
+
+```python
+app = GraphQL(schema, debug=False)
+```

docs/hiding-field-suggestions.md

@@ -0,0 +1,52 @@
+---
+id: hiding-field-suggestions
+title: Hiding field suggestions
+sidebar_label: Hiding field suggestions
+---
+
+## Field suggestion
+
+### Description
+
+The introduction of this feature has enabled the correction of typos in GraphQL requests. It can be employed to infer an introspection schema, even when the latter is closed.
+
+It is therefore recommended to always disable field suggestion, particularly when introspection has been disabled on the application.
+
+````graphql
+query { me { od } }
+````
+
+````json
+{
+ "error": {
+ "errors": [
+ {
+ "message": "Cannot query field 'od' on type 'User'. Did you mean 'id'?",
+ "locations": [
+ {
+ "line": 3,
+ "column": 5
+ }
+ ],
+ "extensions": {
+ "exception": null
+ }
+ }
+ ]
+ }
+}
+````
+
+### Disabling field suggestions
+
+The following code presents an error formatter for that will filter out the suggestions.
+
+```python
+def hide_field_suggestion_fmt(error: GraphQLError, debug: bool = False) -> dict:
+ formatted = error.formatted
+ formatted["message"] = re.sub(r"Did you mean.*", "", formatted["message"])
+ return formatted
+
+schema = make_executable_schema(type_defs, query)
+app = GraphQL(schema, error_formatter=hide_field_suggestion_fmt)
+```

docs/security-overview.md

@@ -0,0 +1,13 @@
+---
+id: security-overview
+title: Security best practices
+sidebar_label: Security Overview
+---
+
+## Security check-list
+
+When deploying a GraphQL application to production, it is important to observe best practices in terms of security.
+
+By default, GraphQL APIs present a broad scope of potential security risks, however these risks can be mitigated through the implementation of appropriate measures. Failure to do so may result in the API being vulnerable to potential issues such as denial of service attacks or credential leakage.
+
+The following outlines the most common vulnerabilities and offers immediate steps to mitigate them with Ariadne.

website/sidebars.json

@@ -26,6 +26,12 @@
  "apollo-tracing",
  "open-tracing"
  ],
+ "Security": [
+ "security-overview",
+ "hiding-field-suggestions",
+ "disabling-stack-traces",
+ "continuous-security-testing"
+ ],
  "Servers": [
  "asgi",
  "wsgi"