From 8774d754cbcf139b08b5eb30d924c582d39bc186 Mon Sep 17 00:00:00 2001 From: Samuel Date: Wed, 5 Nov 2025 20:56:27 +0100 Subject: [PATCH 1/7] draft troubleshooting guide --- docs/troubleshooting.md | 71 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/troubleshooting.md diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..bd11f65c --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,71 @@ +# Troubleshooting + +## Check logs for errors + +Common places: +- Docker: `docker logs ` +- systemd: `journalctl -u --since "1 hour ago"` +- Local dev: your terminal or IDE run console + +Tip: search for lines that contain `Aikido` or `aikido_zen`. + +## Enable debug logs temporarily +Add this early in your app to surface initialization details: + +```python +import logging +logging.basicConfig(level=logging.INFO) +logging.getLogger("aikido_zen").setLevel(logging.INFO) # use DEBUG if needed +``` + +If you use Gunicorn or Uvicorn, also run them with higher verbosity so stdout includes the module logs. + +## Confirm the package is installed + +``` +pip show aikido-zen || python -m pip show aikido-zen +python -c "import importlib; print('ok' if importlib.util.find_spec('aikido_zen') else 'missing')" +``` + +## Confirm it is wired early in the request pipeline +Make sure all requests hit the protection layer before your routes or views. + +FastAPI or Starlette (ASGI) +``` +from fastapi import FastAPI +import aikido_zen + +app = FastAPI() +aikido_zen.protect(app) # add as early as possible, before routes +# define routes after this +``` + +Flask (WSGI) + +``` +from flask import Flask +import aikido_zen + +app = Flask(__name__) +aikido_zen.protect(app) # call before registering blueprints or running the app +``` + + +Django + +In settings.py, add the middleware near the top so it runs before others: + +``` +MIDDLEWARE = [ + "aikido_zen.django.Middleware", # keep this high in the list + # ... your other middleware +] +``` + +Generic ASGI + +``` +import aikido_zen +from your_asgi_app import app +aikido_zen.protect(app) +``` From 927dba9913b1c78efd5a6d6def82f41a3c6710c3 Mon Sep 17 00:00:00 2001 From: Samuel Date: Wed, 5 Nov 2025 21:01:02 +0100 Subject: [PATCH 2/7] added contact support notice --- docs/troubleshooting.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index bd11f65c..80ab500d 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -69,3 +69,12 @@ import aikido_zen from your_asgi_app import app aikido_zen.protect(app) ``` + +## Contact support + +If you still can’t resolve the issue: + +- Use the in-app chat to reach our support team directly. +- Or create an issue on [GitHub](../../issues) with details about your setup, framework, and logs. + +Include as much context as possible (framework, logs, and how Aikido was added) so we can help you quickly. From 70610fd106c93ceba15a77e36bc8dde2ab58d9bb Mon Sep 17 00:00:00 2001 From: Samuel Date: Thu, 6 Nov 2025 09:34:31 +0100 Subject: [PATCH 3/7] added review install steps and check connection --- docs/troubleshooting.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 80ab500d..b0eed0ab 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,5 +1,20 @@ # Troubleshooting +## Review installation steps + +Double-check your setup against the [installation guide](../README.md#installation). +Make sure: +- The package installed correctly. +- The firewall is initialized early in your app (before routes or handlers). +- Your framework-specific integration (middleware, decorator, etc.) matches the example in the README. +- You’re running a supported runtime version for your language. + +## Check connection to Aikido + +The firewall must be able to reach Aikido’s API endpoints. + +Test from the same environment where your app runs and follow the instructions on this page: https://help.aikido.dev/zen-firewall/miscellaneous/outbound-network-connections-for-zen + ## Check logs for errors Common places: From 92238fbe2e62aff892f6c960ba87d86ec09b365e Mon Sep 17 00:00:00 2001 From: Samuel Date: Thu, 6 Nov 2025 09:43:37 +0100 Subject: [PATCH 4/7] little change --- docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index b0eed0ab..0a2483a1 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -30,7 +30,7 @@ Add this early in your app to surface initialization details: ```python import logging logging.basicConfig(level=logging.INFO) -logging.getLogger("aikido_zen").setLevel(logging.INFO) # use DEBUG if needed +logging.getLogger("aikido_zen").setLevel(logging.INFO) # use DEBUG or TRACE if needed ``` If you use Gunicorn or Uvicorn, also run them with higher verbosity so stdout includes the module logs. From 3aa6564437e416bc659b0eb44eba97ff976dbce0 Mon Sep 17 00:00:00 2001 From: Samuel Date: Thu, 6 Nov 2025 11:47:11 +0100 Subject: [PATCH 5/7] removed unneeded content + AIKIDO_DEBUG --- docs/troubleshooting.md | 53 ++--------------------------------------- 1 file changed, 2 insertions(+), 51 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 0a2483a1..ba37f2fe 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -25,64 +25,15 @@ Common places: Tip: search for lines that contain `Aikido` or `aikido_zen`. ## Enable debug logs temporarily -Add this early in your app to surface initialization details: -```python -import logging -logging.basicConfig(level=logging.INFO) -logging.getLogger("aikido_zen").setLevel(logging.INFO) # use DEBUG or TRACE if needed -``` +Set the `AIKIDO_DEBUG=true` environment variable before starting your app to surface initialization and connection details. -If you use Gunicorn or Uvicorn, also run them with higher verbosity so stdout includes the module logs. +This will make Zen log additional information during startup and operation. ## Confirm the package is installed ``` pip show aikido-zen || python -m pip show aikido-zen -python -c "import importlib; print('ok' if importlib.util.find_spec('aikido_zen') else 'missing')" -``` - -## Confirm it is wired early in the request pipeline -Make sure all requests hit the protection layer before your routes or views. - -FastAPI or Starlette (ASGI) -``` -from fastapi import FastAPI -import aikido_zen - -app = FastAPI() -aikido_zen.protect(app) # add as early as possible, before routes -# define routes after this -``` - -Flask (WSGI) - -``` -from flask import Flask -import aikido_zen - -app = Flask(__name__) -aikido_zen.protect(app) # call before registering blueprints or running the app -``` - - -Django - -In settings.py, add the middleware near the top so it runs before others: - -``` -MIDDLEWARE = [ - "aikido_zen.django.Middleware", # keep this high in the list - # ... your other middleware -] -``` - -Generic ASGI - -``` -import aikido_zen -from your_asgi_app import app -aikido_zen.protect(app) ``` ## Contact support From 681a498706b24166a453407140e4fb50abecfb2e Mon Sep 17 00:00:00 2001 From: Samuel Date: Thu, 6 Nov 2025 11:48:18 +0100 Subject: [PATCH 6/7] changed link --- docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ba37f2fe..18595858 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -41,6 +41,6 @@ pip show aikido-zen || python -m pip show aikido-zen If you still can’t resolve the issue: - Use the in-app chat to reach our support team directly. -- Or create an issue on [GitHub](../../issues) with details about your setup, framework, and logs. +- Or create an issue on [GitHub](https://github.com/AikidoSec/firewall-python/issues) with details about your setup, framework, and logs. Include as much context as possible (framework, logs, and how Aikido was added) so we can help you quickly. From 4e4c70dbd6fcad8bfe85167a6eb7c7400df45cc0 Mon Sep 17 00:00:00 2001 From: Samuel Date: Thu, 6 Nov 2025 11:50:26 +0100 Subject: [PATCH 7/7] removed check page as it's also checked in install --- docs/troubleshooting.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 18595858..a26acbe6 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -30,12 +30,6 @@ Set the `AIKIDO_DEBUG=true` environment variable before starting your app to sur This will make Zen log additional information during startup and operation. -## Confirm the package is installed - -``` -pip show aikido-zen || python -m pip show aikido-zen -``` - ## Contact support If you still can’t resolve the issue: